0
# Utility Structures
1

2
Supporting data structures including arrays, stacks, queues, hash maps, and utility functions for comprehensive image processing workflows.
3

4
## Capabilities
5

6
### Data Structures
7

8
Core data structures for organizing and manipulating data in image processing algorithms.
9

10
```java { .api }
11
/**
12
 * Stack data structure
13
 */
14
class L_STACK extends Pointer {
15
    int n(); // number of elements
16
    int nalloc(); // allocated capacity
17
    Pointer auxstack(); // auxiliary stack for object pointers
18
}
19

20
/**
21
 * Queue data structure
22
 */
23
class L_QUEUE extends Pointer {
24
    int nalloc(); // allocated capacity
25
    int nhead(); // head index
26
    int ntail(); // tail index
27
    int nelem(); // number of elements
28
    Pointer array(); // element array
29
}
30

31
/**
32
 * Priority heap
33
 */
34
class L_HEAP extends Pointer {
35
    int n(); // number of elements
36
    int nalloc(); // allocated capacity
37
    FloatPointer array(); // value array
38
    int direction(); // L_SORT_INCREASING or L_SORT_DECREASING
39
}
40

41
/**
42
 * Hash map
43
 */
44
class L_HASHMAP extends Pointer {
45
    int nitems(); // number of items
46
    int nbuckets(); // number of hash buckets
47
    L_HASHITEM array(); // hash item array
48
}
49

50
/**
51
 * Hash map item
52
 */
53
class L_HASHITEM extends Pointer {
54
    long key(); // hash key
55
    Pointer value(); // stored value
56
    L_HASHITEM next(); // next item in bucket
57
}
58

59
// Stack operations
60
L_STACK lstackCreate(int nalloc);
61
int lstackAdd(L_STACK lstack, Pointer item);
62
Pointer lstackRemove(L_STACK lstack);
63
int lstackGetCount(L_STACK lstack);
64

65
// Queue operations
66
L_QUEUE lqueueCreate(int nalloc);
67
int lqueueAdd(L_QUEUE lqueue, Pointer item);
68
Pointer lqueueRemove(L_QUEUE lqueue);
69
int lqueueGetCount(L_QUEUE lqueue);
70

71
// Heap operations
72
L_HEAP lheapCreate(int nalloc, int direction);
73
int lheapAdd(L_HEAP lh, Pointer item);
74
Pointer lheapRemove(L_HEAP lh);
75
int lheapGetCount(L_HEAP lh);
76

77
// Hash map operations
78
L_HASHMAP hashmapCreate(int nbuckets);
79
int hashmapLookup(L_HASHMAP hmap, long key, Pointer pval);
80
int hashmapInsert(L_HASHMAP hmap, long key, Pointer val);
81
int hashmapDelete(L_HASHMAP hmap, long key);
82
```
83

84
**Usage Examples:**
85

86
```java
87
import org.bytedeco.leptonica.*;
88
import static org.bytedeco.leptonica.global.leptonica.*;
89

90
// Stack for region processing
91
L_STACK regionStack = lstackCreate(100);
92
lstackAdd(regionStack, seedRegion);
93

94
while (lstackGetCount(regionStack) > 0) {
95
    BOX region = (BOX)lstackRemove(regionStack);
96
    // Process region and add neighbors...
97
}
98

99
// Priority queue for pathfinding
100
L_HEAP priorityQueue = lheapCreate(500, L_SORT_INCREASING);
101
lheapAdd(priorityQueue, startNode);
102

103
while (lheapGetCount(priorityQueue) > 0) {
104
    PathNode current = (PathNode)lheapRemove(priorityQueue);
105
    // Process current node...
106
}
107

108
// Hash map for caching results
109
L_HASHMAP cache = hashmapCreate(1024);
110
hashmapInsert(cache, imageHash, processedResult);
111

112
// Later lookup
113
Pointer cached = new Pointer();
114
if (hashmapLookup(cache, imageHash, cached) == 0) {
115
    // Use cached result
116
}
117
```
118

119
### Byte Arrays and Buffers
120

121
Dynamic byte arrays and buffers for I/O operations and data manipulation.
122

123
```java { .api }
124
/**
125
 * Dynamic byte array
126
 */
127
class L_BYTEA extends Pointer {
128
    int nalloc(); // allocated size
129
    int size(); // actual size
130
    BytePointer data(); // byte data
131
}
132

133
/**
134
 * Byte buffer for I/O
135
 */
136
class L_BBUFFER extends Pointer {
137
    int nalloc(); // allocated size
138
    int n(); // actual size
139
    int nwritten(); // bytes written
140
    BytePointer array(); // buffer data
141
}
142

143
/**
144
 * Create byte array
145
 * @param nbytes - Initial capacity
146
 * @return L_BYTEA or null on failure
147
 */
148
L_BYTEA l_byteaCreate(int nbytes);
149

150
/**
151
 * Append data to byte array
152
 * @param ba - Target byte array
153
 * @param newdata - Data to append
154
 * @param size - Size of data
155
 * @return 0 on success, 1 on failure
156
 */
157
int l_byteaAppendData(L_BYTEA ba, BytePointer newdata, int size);
158

159
/**
160
 * Get data from byte array
161
 * @param ba - Source byte array
162
 * @param psize - Returns data size
163
 * @return BytePointer to data or null on failure
164
 */
165
BytePointer l_byteaGetData(L_BYTEA ba, IntPointer psize);
166

167
/**
168
 * Create byte buffer
169
 * @param nbytes - Initial capacity
170
 * @return L_BBUFFER or null on failure
171
 */
172
L_BBUFFER bbufferCreate(int nbytes);
173

174
/**
175
 * Read data into buffer
176
 * @param bb - Target buffer
177
 * @param src - Source data
178
 * @param nbytes - Number of bytes to read
179
 * @return 0 on success, 1 on failure
180
 */
181
int bbufferRead(L_BBUFFER bb, BytePointer src, int nbytes);
182

183
/**
184
 * Write data from buffer
185
 * @param bb - Source buffer
186
 * @param dest - Destination
187
 * @param nbytes - Number of bytes to write
188
 * @return 0 on success, 1 on failure
189
 */
190
int bbufferWrite(L_BBUFFER bb, BytePointer dest, int nbytes);
191
```
192

193
**Usage Examples:**
194

195
```java
196
// Dynamic byte array for accumulating data
197
L_BYTEA accumulator = l_byteaCreate(1024);
198

199
// Append image data
200
BytePointer imageData = pixGetData(pix);
201
int imageSize = pixGetHeight(pix) * pixGetWpl(pix) * 4;
202
l_byteaAppendData(accumulator, imageData, imageSize);
203

204
// Get accumulated data
205
IntPointer totalSize = new IntPointer(1);
206
BytePointer allData = l_byteaGetData(accumulator, totalSize);
207
System.out.println("Accumulated " + totalSize.get() + " bytes");
208

209
// Byte buffer for I/O operations
210
L_BBUFFER buffer = bbufferCreate(4096);
211
bbufferRead(buffer, inputData, dataSize);
212
// ... process buffer ...
213
bbufferWrite(buffer, outputData, processedSize);
214
```
215

216
### Timing and Performance
217

218
Timing utilities for performance measurement and profiling.
219

220
```java { .api }
221
/**
222
 * Timer structure
223
 */
224
class L_TIMER extends Pointer {
225
    // Internal timer state
226
}
227

228
/**
229
 * Wall clock timer
230
 */
231
class L_WALLTIMER extends Pointer {
232
    long start_sec(); // start seconds
233
    long start_usec(); // start microseconds
234
    long stop_sec(); // stop seconds
235
    long stop_usec(); // stop microseconds
236
}
237

238
/**
239
 * Start timing
240
 * @return L_TIMER or null on failure
241
 */
242
L_TIMER startTimer();
243

244
/**
245
 * Stop timing and get elapsed time
246
 * @param timer - Timer to stop
247
 * @return Elapsed time in seconds
248
 */
249
float stopTimer(L_TIMER timer);
250

251
/**
252
 * Start wall clock timer
253
 * @return L_WALLTIMER or null on failure
254
 */
255
L_WALLTIMER startWallTimer();
256

257
/**
258
 * Stop wall clock timer
259
 * @param timer - Wall timer to stop
260
 * @return Elapsed time in seconds
261
 */
262
float stopWallTimer(L_WALLTIMER timer);
263

264
/**
265
 * Get current timestamp
266
 * @return Current time in seconds since epoch
267
 */
268
float getCurrentTime();
269
```
270

271
**Usage Examples:**
272

273
```java
274
// Time image processing operation
275
L_TIMER timer = startTimer();
276

277
PIX processed = pixGaussianBlur(sourceImage, 3.0f, 3.0f);
278
processed = pixScale(processed, 2.0f, 2.0f);
279
processed = pixRotate(processed, 0.1f, L_ROTATE_AREA_MAP, L_BRING_IN_WHITE, 0, 0);
280

281
float elapsed = stopTimer(timer);
282
System.out.println("Processing took " + elapsed + " seconds");
283

284
// Wall clock timing for I/O operations
285
L_WALLTIMER wallTimer = startWallTimer();
286

287
for (int i = 0; i < 100; i++) {
288
    PIX image = pixRead("image_" + i + ".jpg");
289
    PIX result = pixScale(image, 0.5f, 0.5f);
290
    pixWrite("thumb_" + i + ".jpg", result, IFF_JPEG);
291
}
292

293
float totalTime = stopWallTimer(wallTimer);
294
System.out.println("Batch processing: " + totalTime + " seconds");
295
```
296

297
### Utility Functions
298

299
Miscellaneous utility functions for common operations and calculations.
300

301
```java { .api }
302
/**
303
 * Count pixels in binary image
304
 * @param pix - Binary image
305
 * @param pcount - Returns pixel count
306
 * @param tab8 - Lookup table (can be null)
307
 * @return 0 on success, 1 on failure
308
 */
309
int pixCountPixels(PIX pix, IntPointer pcount, IntPointer tab8);
310

311
/**
312
 * Get average pixel value in region
313
 * @param pixs - Source image
314
 * @param pixm - Mask image (can be null)
315
 * @param x - Region x coordinate
316
 * @param y - Region y coordinate
317
 * @param w - Region width
318
 * @param h - Region height
319
 * @param factor - Sampling factor
320
 * @param pval - Returns average value
321
 * @return 0 on success, 1 on failure
322
 */
323
int pixGetAverageMasked(PIX pixs, PIX pixm, int x, int y, int w, int h, int factor, FloatPointer pval);
324

325
/**
326
 * Get pixel variance in region
327
 * @param pixs - Source image
328
 * @param pixm - Mask image (can be null)
329
 * @param x - Region x coordinate  
330
 * @param y - Region y coordinate
331
 * @param w - Region width
332
 * @param h - Region height
333
 * @param factor - Sampling factor
334
 * @param pvar - Returns variance
335
 * @return 0 on success, 1 on failure
336
 */
337
int pixGetVarianceMasked(PIX pixs, PIX pixm, int x, int y, int w, int h, int factor, FloatPointer pvar);
338

339
/**
340
 * Find extreme pixel values
341
 * @param pixs - Source image
342
 * @param pminval - Returns minimum value (can be null)
343
 * @param pmaxval - Returns maximum value (can be null)
344
 * @param pminloc - Returns minimum location (can be null)
345
 * @param pmaxloc - Returns maximum location (can be null)
346
 * @return 0 on success, 1 on failure
347
 */
348
int pixGetExtremeValue(PIX pixs, IntPointer pminval, IntPointer pmaxval, IntPointer pminloc, IntPointer pmaxloc);
349

350
/**
351
 * Check if images are equal
352
 * @param pix1 - First image
353
 * @param pix2 - Second image
354
 * @param psame - Returns 1 if equal, 0 otherwise
355
 * @return 0 on success, 1 on failure
356
 */
357
int pixEqual(PIX pix1, PIX pix2, IntPointer psame);
358

359
/**
360
 * Calculate correlation between images
361
 * @param pix1 - First image
362
 * @param pix2 - Second image
363
 * @param pcorrel - Returns correlation coefficient
364
 * @return 0 on success, 1 on failure
365
 */
366
int pixCorrelationBinary(PIX pix1, PIX pix2, FloatPointer pcorrel);
367
```
368

369
**Usage Examples:**
370

371
```java
372
// Count foreground pixels
373
IntPointer pixelCount = new IntPointer(1);
374
pixCountPixels(binaryImage, pixelCount, null);
375
System.out.println("Foreground pixels: " + pixelCount.get());
376

377
// Get region statistics
378
FloatPointer average = new FloatPointer(1);
379
FloatPointer variance = new FloatPointer(1);
380

381
pixGetAverageMasked(grayImage, null, 100, 100, 50, 50, 1, average);
382
pixGetVarianceMasked(grayImage, null, 100, 100, 50, 50, 1, variance);
383

384
System.out.println("Region stats: mean=" + average.get() + ", var=" + variance.get());
385

386
// Find extreme values
387
IntPointer minVal = new IntPointer(1);
388
IntPointer maxVal = new IntPointer(1);
389
IntPointer minLoc = new IntPointer(1);
390
IntPointer maxLoc = new IntPointer(1);
391

392
pixGetExtremeValue(grayImage, minVal, maxVal, minLoc, maxLoc);
393
System.out.println("Range: " + minVal.get() + " to " + maxVal.get());
394

395
// Compare images
396
IntPointer same = new IntPointer(1);
397
pixEqual(image1, image2, same);
398
if (same.get() == 1) {
399
    System.out.println("Images are identical");
400
}
401

402
// Calculate similarity
403
FloatPointer correlation = new FloatPointer(1);
404
pixCorrelationBinary(binary1, binary2, correlation);
405
System.out.println("Correlation: " + correlation.get());
406
```
407

408
### Memory Management Utilities
409

410
Memory allocation and management utilities for native operations.
411

412
```java { .api }
413
/**
414
 * Allocate memory
415
 * @param nbytes - Number of bytes to allocate
416
 * @return Pointer to allocated memory or null on failure
417
 */
418
Pointer lept_malloc(long nbytes);
419

420
/**
421
 * Reallocate memory
422
 * @param ptr - Existing pointer
423
 * @param nbytes - New size in bytes
424
 * @return Pointer to reallocated memory or null on failure
425
 */
426
Pointer lept_realloc(Pointer ptr, long nbytes);
427

428
/**
429
 * Free memory
430
 * @param ptr - Pointer to free
431
 */
432
void lept_free(Pointer ptr);
433

434
/**
435
 * Get memory usage statistics
436
 * @param pnalloc - Returns number of allocations
437
 * @param pnfree - Returns number of frees
438
 * @param pnbytes - Returns bytes allocated
439
 * @return 0 on success, 1 on failure
440
 */
441
int lept_getAllocStats(IntPointer pnalloc, IntPointer pnfree, IntPointer pnbytes);
442
```
443

444
**Usage Examples:**
445

446
```java
447
// Manual memory management (rarely needed with JavaCPP)
448
Pointer buffer = lept_malloc(1024);
449
// ... use buffer ...
450
lept_free(buffer);
451

452
// Check memory statistics
453
IntPointer allocCount = new IntPointer(1);
454
IntPointer freeCount = new IntPointer(1); 
455
IntPointer bytesAlloc = new IntPointer(1);
456

457
lept_getAllocStats(allocCount, freeCount, bytesAlloc);
458
System.out.println("Memory: " + allocCount.get() + " allocs, " + 
459
                  freeCount.get() + " frees, " + bytesAlloc.get() + " bytes");
460
```
461

462
## Constants
463

464
```java { .api }
465
// Direction constants
466
static final int L_SORT_INCREASING = 1;
467
static final int L_SORT_DECREASING = 2;
468

469
// Access flags
470
static final int L_COPY = 0;
471
static final int L_CLONE = 1;
472
static final int L_INSERT = 2;
473
static final int L_NOCOPY = 3;
474

475
// Buffer sizes
476
static final int L_DEFAULT_BUFFER_SIZE = 4096;
477
```
478

479
## Integration with Image Processing
480

481
Utility structures integrate seamlessly with image processing workflows:
482

483
```java
484
// Region growing with stack
485
L_STACK growStack = lstackCreate(1000);
486
lstackAdd(growStack, seedPoint);
487

488
while (lstackGetCount(growStack) > 0) {
489
    Point current = (Point)lstackRemove(growStack);
490
    
491
    // Check neighbors and add to stack
492
    if (isValidGrowthPoint(current.x + 1, current.y)) {
493
        lstackAdd(growStack, new Point(current.x + 1, current.y));
494
    }
495
    // ... check other neighbors ...
496
}
497

498
// Performance monitoring
499
L_TIMER overallTimer = startTimer();
500

501
for (int i = 0; i < imageCount; i++) {
502
    L_TIMER imageTimer = startTimer();
503
    
504
    PIX processed = processImage(images[i]);
505
    
506
    float imageTime = stopTimer(imageTimer);
507
    System.out.println("Image " + i + ": " + imageTime + " seconds");
508
}
509

510
float totalTime = stopTimer(overallTimer);
511
System.out.println("Total processing: " + totalTime + " seconds");
512
```