0
# Image Collections
1

2
Container classes for organizing and manipulating groups of images, rectangles, and associated metadata with efficient array-based operations.
3

4
## Capabilities
5

6
### PIXA - Image Arrays
7

8
Manage collections of PIX images with optional associated bounding boxes for multi-image processing workflows.
9

10
```java { .api }
11
/**
12
 * Array of PIX images with optional associated boxes
13
 */
14
class PIXA extends Pointer {
15
    int n(); // number of images in array
16
    int nalloc(); // allocated array size
17
}
18

19
/**
20
 * Create image array
21
 * @param n - Initial capacity
22
 * @return PIXA array or null on failure
23
 */
24
PIXA pixaCreate(int n);
25

26
/**
27
 * Add image to array
28
 * @param pixa - Target array
29
 * @param pix - Image to add
30
 * @param copyflag - L_INSERT, L_COPY, or L_CLONE
31
 * @return 0 on success, 1 on failure
32
 */
33
int pixaAddPix(PIXA pixa, PIX pix, int copyflag);
34

35
/**
36
 * Get image from array
37
 * @param pixa - Source array
38
 * @param index - Image index
39
 * @param accesstype - L_COPY or L_CLONE
40
 * @return PIX image or null on failure
41
 */
42
PIX pixaGetPix(PIXA pixa, int index, int accesstype);
43

44
/**
45
 * Get number of images
46
 * @param pixa - Source array
47
 * @return Number of images
48
 */
49
int pixaGetCount(PIXA pixa);
50

51
/**
52
 * Get associated bounding boxes
53
 * @param pixa - Source array
54
 * @param accesstype - L_COPY or L_CLONE
55
 * @return BOXA array of boxes or null
56
 */
57
BOXA pixaGetBoxa(PIXA pixa, int accesstype);
58

59
/**
60
 * Set bounding boxes for images
61
 * @param pixa - Target array
62
 * @param boxa - Array of bounding boxes
63
 * @param accesstype - L_INSERT, L_COPY, or L_CLONE
64
 * @return 0 on success, 1 on failure
65
 */
66
int pixaSetBoxa(PIXA pixa, BOXA boxa, int accesstype);
67

68
/**
69
 * Add image with associated box
70
 * @param pixa - Target array
71
 * @param pix - Image to add
72
 * @param box - Associated bounding box (can be null)
73
 * @param copyflag - L_INSERT, L_COPY, or L_CLONE
74
 * @return 0 on success, 1 on failure
75
 */
76
int pixaAddPixWithBox(PIXA pixa, PIX pix, BOX box, int copyflag);
77

78
/**
79
 * Sort images by various criteria
80
 * @param pixas - Source array
81
 * @param sorttype - L_SORT_BY_* constant
82
 * @param sortorder - L_SORT_INCREASING or L_SORT_DECREASING
83
 * @param pnaindex - Returns sort indices (can be null)
84
 * @return Sorted PIXA or null on failure
85
 */
86
PIXA pixaSort(PIXA pixas, int sorttype, int sortorder, NUMA naindex);
87
```
88

89
**Usage Examples:**
90

91
```java
92
import org.bytedeco.leptonica.*;
93
import static org.bytedeco.leptonica.global.leptonica.*;
94

95
// Create image collection for processing results
96
PIXA results = pixaCreate(10);
97

98
// Add processed images
99
pixaAddPix(results, processedImage1, L_COPY);
100
pixaAddPix(results, processedImage2, L_COPY);
101
pixaAddPix(results, processedImage3, L_COPY);
102

103
// Add images with bounding boxes
104
BOX region1 = boxCreate(0, 0, 100, 100);
105
pixaAddPixWithBox(results, croppedImage, region1, L_COPY);
106

107
// Process each image in collection
108
int count = pixaGetCount(results);
109
for (int i = 0; i < count; i++) {
110
    PIX pix = pixaGetPix(results, i, L_CLONE);
111
    
112
    // Apply additional processing
113
    PIX enhanced = pixGaussianBlur(pix, 1.0f, 1.0f);
114
    
115
    // Replace in collection
116
    pixaReplacePix(results, i, enhanced, null);
117
}
118

119
// Sort by image area
120
PIXA sorted = pixaSort(results, L_SORT_BY_AREA, L_SORT_DECREASING, null);
121
```
122

123
### PIXAA - 2D Image Arrays
124

125
Manage 2D arrays of image collections for hierarchical organization and batch processing.
126

127
```java { .api }
128
/**
129
 * 2D array of PIXA image collections
130
 */
131
class PIXAA extends Pointer {
132
    int n(); // number of PIXA arrays
133
    int nalloc(); // allocated array size
134
}
135

136
/**
137
 * Create 2D image array
138
 * @param n - Initial capacity
139
 * @return PIXAA array or null on failure
140
 */
141
PIXAA pixaaCreate(int n);
142

143
/**
144
 * Add PIXA to 2D array
145
 * @param pixaa - Target 2D array
146
 * @param pixa - PIXA to add
147
 * @param copyflag - L_INSERT, L_COPY, or L_CLONE
148
 * @return 0 on success, 1 on failure
149
 */
150
int pixaaAddPixa(PIXAA pixaa, PIXA pixa, int copyflag);
151

152
/**
153
 * Get PIXA from 2D array
154
 * @param pixaa - Source 2D array
155
 * @param index - PIXA index
156
 * @param accesstype - L_COPY or L_CLONE
157
 * @return PIXA array or null on failure
158
 */
159
PIXA pixaaGetPixa(PIXAA pixaa, int index, int accesstype);
160

161
/**
162
 * Get specific image from 2D array
163
 * @param pixaa - Source 2D array
164
 * @param i - PIXA index
165
 * @param j - PIX index within PIXA
166
 * @param accesstype - L_COPY or L_CLONE
167
 * @return PIX image or null on failure
168
 */
169
PIX pixaaGetPix(PIXAA pixaa, int i, int j, int accesstype);
170
```
171

172
**Usage Examples:**
173

174
```java
175
// Organize images by processing stage
176
PIXAA workflow = pixaaCreate(5);
177

178
// Stage 1: Original images
179
PIXA originals = pixaCreate(10);
180
pixaAddPix(originals, image1, L_COPY);
181
pixaAddPix(originals, image2, L_COPY);
182
pixaaAddPixa(workflow, originals, L_INSERT);
183

184
// Stage 2: Preprocessed images
185
PIXA preprocessed = pixaCreate(10);
186
// ... add preprocessed images ...
187
pixaaAddPixa(workflow, preprocessed, L_INSERT);
188

189
// Access specific image from workflow
190
PIX result = pixaaGetPix(workflow, 1, 0, L_CLONE); // Stage 1, Image 0
191
```
192

193
### NUMA - Number Arrays
194

195
Manage arrays of numbers for statistical analysis, measurements, and numerical computations.
196

197
```java { .api }
198
/**
199
 * Array of numbers for statistical operations
200
 */
201
class NUMA extends Pointer {
202
    int n(); // number of values
203
    int nalloc(); // allocated array size
204
    FloatPointer array(); // array data
205
}
206

207
/**
208
 * Create number array
209
 * @param n - Initial capacity
210
 * @return NUMA array or null on failure
211
 */
212
NUMA numaCreate(int n);
213

214
/**
215
 * Add number to array
216
 * @param na - Target array
217
 * @param val - Value to add
218
 * @return 0 on success, 1 on failure
219
 */
220
int numaAddNumber(NUMA na, float val);
221

222
/**
223
 * Get number from array
224
 * @param na - Source array
225
 * @param index - Value index
226
 * @param pval - Returns value
227
 * @return 0 on success, 1 on failure
228
 */
229
int numaGetFValue(NUMA na, int index, FloatPointer pval);
230

231
/**
232
 * Get array statistics
233
 * @param na - Source array
234
 * @param pmin - Returns minimum value (can be null)
235
 * @param pmax - Returns maximum value (can be null)
236
 * @param pmean - Returns mean value (can be null)
237
 * @param pvar - Returns variance (can be null)
238
 * @return 0 on success, 1 on failure
239
 */
240
int numaGetStatsValues(NUMA na, FloatPointer pmin, FloatPointer pmax, FloatPointer pmean, FloatPointer pvar);
241

242
/**
243
 * Sort number array
244
 * @param nas - Source array
245
 * @param sortorder - L_SORT_INCREASING or L_SORT_DECREASING
246
 * @param pnaindex - Returns sort indices (can be null)
247
 * @return Sorted NUMA or null on failure
248
 */
249
NUMA numaSort(NUMA nas, int sortorder, NUMA naindex);
250
```
251

252
**Usage Examples:**
253

254
```java
255
// Collect measurement data
256
NUMA measurements = numaCreate(100);
257

258
// Add measurements from image analysis
259
numaAddNumber(measurements, 156.7f);
260
numaAddNumber(measurements, 142.3f);
261
numaAddNumber(measurements, 198.1f);
262

263
// Get statistics
264
FloatPointer min = new FloatPointer(1);
265
FloatPointer max = new FloatPointer(1);
266
FloatPointer mean = new FloatPointer(1);
267
FloatPointer variance = new FloatPointer(1);
268

269
numaGetStatsValues(measurements, min, max, mean, variance);
270
System.out.println("Measurements: min=" + min.get() + ", max=" + max.get() + 
271
                  ", mean=" + mean.get() + ", var=" + variance.get());
272

273
// Sort for analysis
274
NUMA sorted = numaSort(measurements, L_SORT_INCREASING, null);
275
```
276

277
### SARRAY - String Arrays
278

279
Manage collections of strings for text processing, filenames, and metadata.
280

281
```java { .api }
282
/**
283
 * Array of strings
284
 */
285
class SARRAY extends Pointer {
286
    int n(); // number of strings
287
    int nalloc(); // allocated array size
288
}
289

290
/**
291
 * Create string array
292
 * @param n - Initial capacity
293
 * @return SARRAY array or null on failure
294
 */
295
SARRAY sarrayCreate(int n);
296

297
/**
298
 * Add string to array
299
 * @param sa - Target array
300
 * @param string - String to add
301
 * @param copyflag - L_INSERT or L_COPY
302
 * @return 0 on success, 1 on failure
303
 */
304
int sarrayAddString(SARRAY sa, String string, int copyflag);
305

306
/**
307
 * Get string from array
308
 * @param sa - Source array
309
 * @param index - String index
310
 * @param copyflag - L_COPY or L_NOCOPY
311
 * @return String or null on failure
312
 */
313
String sarrayGetString(SARRAY sa, int index, int copyflag);
314

315
/**
316
 * Get number of strings
317
 * @param sa - Source array
318
 * @return Number of strings
319
 */
320
int sarrayGetCount(SARRAY sa);
321

322
/**
323
 * Sort string array
324
 * @param sas - Source array
325
 * @param sortorder - L_SORT_INCREASING or L_SORT_DECREASING
326
 * @return Sorted SARRAY or null on failure
327
 */
328
SARRAY sarraySort(SARRAY sas, int sortorder);
329
```
330

331
**Usage Examples:**
332

333
```java
334
// Collect image filenames
335
SARRAY filenames = sarrayCreate(50);
336

337
sarrayAddString(filenames, "image001.jpg", L_COPY);
338
sarrayAddString(filenames, "image002.jpg", L_COPY);
339
sarrayAddString(filenames, "processed_001.png", L_COPY);
340

341
// Process each file
342
int count = sarrayGetCount(filenames);
343
for (int i = 0; i < count; i++) {
344
    String filename = sarrayGetString(filenames, i, L_NOCOPY);
345
    PIX pix = pixRead(filename);
346
    // Process image...
347
}
348

349
// Sort alphabetically
350
SARRAY sorted = sarraySort(filenames, L_SORT_INCREASING);
351
```
352

353
## Collection Operations
354

355
### Batch Processing
356

357
```java { .api }
358
/**
359
 * Apply function to all images in PIXA
360
 * @param pixas - Source image array
361
 * @param func - Processing function
362
 * @param param - Function parameter
363
 * @return Processed PIXA or null on failure
364
 */
365
PIXA pixaApplyFunction(PIXA pixas, PIXFunction func, Pointer param);
366

367
/**
368
 * Join multiple PIXA arrays
369
 * @param pixa1 - First array
370
 * @param pixa2 - Second array
371
 * @return Combined PIXA or null on failure
372
 */
373
PIXA pixaJoin(PIXA pixa1, PIXA pixa2);
374

375
/**
376
 * Select subset of images
377
 * @param pixas - Source array
378
 * @param start - Start index
379
 * @param end - End index
380
 * @return Subset PIXA or null on failure
381
 */
382
PIXA pixaSelectRange(PIXA pixas, int start, int end);
383
```
384

385
**Usage Examples:**
386

387
```java
388
// Apply gaussian blur to all images
389
PIXA blurred = pixaApplyFunction(originalImages, pixGaussianBlur, new FloatPointer(2.0f));
390

391
// Combine processing results
392
PIXA combined = pixaJoin(results1, results2);
393

394
// Select images for further processing
395
PIXA subset = pixaSelectRange(allImages, 10, 20);
396
```
397

398
## Memory Management
399

400
All collection classes use reference counting and automatic cleanup:
401

402
```java
403
// Collections automatically manage contained objects
404
PIXA images = pixaCreate(10);
405
pixaAddPix(images, pix, L_COPY); // Image is copied and managed
406

407
// Access creates new references
408
PIX retrieved = pixaGetPix(images, 0, L_CLONE); // Increases reference count
409

410
// Memory freed when all references released
411
// No manual cleanup required with JavaCPP
412
```