0
# Geometric Operations
1

2
Rectangle and point operations for defining regions, measuring features, and spatial analysis with comprehensive support for geometric calculations and transformations.
3

4
## Capabilities
5

6
### BOX - Rectangle Operations
7

8
Define and manipulate rectangular regions for clipping, analysis, and region-of-interest operations.
9

10
```java { .api }
11
/**
12
 * Rectangle structure for defining image regions
13
 */
14
class BOX extends Pointer {
15
    // Rectangle properties
16
    int x(); // left coordinate
17
    int y(); // top coordinate  
18
    int w(); // width
19
    int h(); // height
20
    int refcount(); // reference count for memory management
21
    
22
    // Setters
23
    BOX x(int x);
24
    BOX y(int y);
25
    BOX w(int w);
26
    BOX h(int h);
27
}
28

29
/**
30
 * Create rectangle
31
 * @param x - Left coordinate
32
 * @param y - Top coordinate
33
 * @param w - Width
34
 * @param h - Height
35
 * @return BOX rectangle or null on failure
36
 */
37
BOX boxCreate(int x, int y, int w, int h);
38

39
/**
40
 * Copy rectangle
41
 * @param box - Source rectangle
42
 * @return BOX copy or null on failure
43
 */
44
BOX boxCopy(BOX box);
45

46
/**
47
 * Get rectangle geometry
48
 * @param box - Source rectangle
49
 * @param px - Returns x coordinate (can be null)
50
 * @param py - Returns y coordinate (can be null)
51
 * @param pw - Returns width (can be null)
52
 * @param ph - Returns height (can be null)
53
 * @return 0 on success, 1 on failure
54
 */
55
int boxGetGeometry(BOX box, IntPointer px, IntPointer py, IntPointer pw, IntPointer ph);
56

57
/**
58
 * Set rectangle geometry
59
 * @param box - Target rectangle
60
 * @param x - Left coordinate
61
 * @param y - Top coordinate
62
 * @param w - Width
63
 * @param h - Height
64
 * @return 0 on success, 1 on failure
65
 */
66
int boxSetGeometry(BOX box, int x, int y, int w, int h);
67

68
/**
69
 * Rectangle intersection
70
 * @param box1 - First rectangle
71
 * @param box2 - Second rectangle
72
 * @return BOX intersection or null if no overlap
73
 */
74
BOX boxIntersection(BOX box1, BOX box2);
75

76
/**
77
 * Rectangle union (bounding box)
78
 * @param box1 - First rectangle
79
 * @param box2 - Second rectangle
80
 * @return BOX union or null on failure
81
 */
82
BOX boxBoundingRegion(BOX box1, BOX box2);
83

84
/**
85
 * Check if rectangles overlap
86
 * @param box1 - First rectangle
87
 * @param box2 - Second rectangle
88
 * @param presult - Returns 1 if overlap, 0 otherwise
89
 * @return 0 on success, 1 on failure
90
 */
91
int boxOverlapRegion(BOX box1, BOX box2, IntPointer presult);
92

93
/**
94
 * Check if point is inside rectangle
95
 * @param box - Rectangle
96
 * @param x - Point x coordinate
97
 * @param y - Point y coordinate
98
 * @param presult - Returns 1 if inside, 0 otherwise
99
 * @return 0 on success, 1 on failure
100
 */
101
int boxContainsPt(BOX box, float x, float y, IntPointer presult);
102
```
103

104
**Usage Examples:**
105

106
```java
107
import org.bytedeco.leptonica.*;
108
import static org.bytedeco.leptonica.global.leptonica.*;
109

110
// Create rectangle for region of interest
111
BOX roi = boxCreate(100, 50, 200, 150);
112

113
// Get rectangle properties
114
IntPointer x = new IntPointer(1);
115
IntPointer y = new IntPointer(1);
116
IntPointer w = new IntPointer(1);
117
IntPointer h = new IntPointer(1);
118
boxGetGeometry(roi, x, y, w, h);
119
System.out.println("ROI: " + x.get() + "," + y.get() + " " + w.get() + "x" + h.get());
120

121
// Check intersection
122
BOX region1 = boxCreate(0, 0, 100, 100);
123
BOX region2 = boxCreate(50, 50, 100, 100);
124
BOX overlap = boxIntersection(region1, region2);
125
if (overlap != null) {
126
    System.out.println("Regions overlap");
127
}
128

129
// Check if point is inside rectangle
130
IntPointer inside = new IntPointer(1);
131
boxContainsPt(roi, 150, 100, inside);
132
if (inside.get() == 1) {
133
    System.out.println("Point is inside ROI");
134
}
135

136
// Extract image region
137
PIX clipped = pixClipRectangle(sourcePix, roi, null);
138
```
139

140
### BOXA - Rectangle Arrays
141

142
Manage collections of rectangles for multi-region operations and analysis.
143

144
```java { .api }
145
/**
146
 * Array of BOX rectangles
147
 */
148
class BOXA extends Pointer {
149
    int n(); // number of boxes
150
    int nalloc(); // allocated array size
151
}
152

153
/**
154
 * Create rectangle array
155
 * @param n - Initial capacity
156
 * @return BOXA array or null on failure
157
 */
158
BOXA boxaCreate(int n);
159

160
/**
161
 * Add rectangle to array
162
 * @param boxa - Target array
163
 * @param box - Rectangle to add
164
 * @param copyflag - L_INSERT or L_COPY
165
 * @return 0 on success, 1 on failure
166
 */
167
int boxaAddBox(BOXA boxa, BOX box, int copyflag);
168

169
/**
170
 * Get rectangle from array
171
 * @param boxa - Source array
172
 * @param index - Rectangle index
173
 * @param accessflag - L_COPY or L_CLONE
174
 * @return BOX rectangle or null on failure
175
 */
176
BOX boxaGetBox(BOXA boxa, int index, int accessflag);
177

178
/**
179
 * Get number of rectangles
180
 * @param boxa - Source array
181
 * @return Number of rectangles
182
 */
183
int boxaGetCount(BOXA boxa);
184

185
/**
186
 * Get bounding box of all rectangles
187
 * @param boxa - Source array
188
 * @return BOX bounding box or null on failure
189
 */
190
BOX boxaBinSort(BOXA boxa, int sorttype, int sortorder, NUMA naindex);
191

192
/**
193
 * Sort rectangles by various criteria
194
 * @param boxas - Source array
195
 * @param sorttype - Sort criteria (L_SORT_BY_*)
196
 * @param sortorder - L_SORT_INCREASING or L_SORT_DECREASING
197
 * @param pnaindex - Returns sort indices (can be null)
198
 * @return Sorted BOXA or null on failure
199
 */
200
BOXA boxaSort(BOXA boxas, int sorttype, int sortorder, NUMA naindex);
201
```
202

203
**Usage Examples:**
204

205
```java
206
// Create array for multiple regions
207
BOXA regions = boxaCreate(10);
208

209
// Add rectangles
210
boxaAddBox(regions, boxCreate(0, 0, 100, 100), L_COPY);
211
boxaAddBox(regions, boxCreate(200, 150, 150, 200), L_COPY);
212
boxaAddBox(regions, boxCreate(400, 50, 120, 180), L_COPY);
213

214
// Process each region
215
int count = boxaGetCount(regions);
216
for (int i = 0; i < count; i++) {
217
    BOX box = boxaGetBox(regions, i, L_CLONE);
218
    PIX region = pixClipRectangle(sourcePix, box, null);
219
    
220
    // Process region...
221
    System.out.println("Processing region " + i);
222
}
223

224
// Sort rectangles by area
225
BOXA sorted = boxaSort(regions, L_SORT_BY_AREA, L_SORT_DECREASING, null);
226
```
227

228
### PTA - Point Arrays
229

230
Manage arrays of 2D points for geometric calculations, curve fitting, and spatial analysis.
231

232
```java { .api }
233
/**
234
 * Array of 2D points
235
 */
236
class PTA extends Pointer {
237
    int n(); // number of points
238
    int nalloc(); // allocated array size
239
}
240

241
/**
242
 * Create point array
243
 * @param n - Initial capacity
244
 * @return PTA array or null on failure
245
 */
246
PTA ptaCreate(int n);
247

248
/**
249
 * Add point to array
250
 * @param pta - Target array
251
 * @param x - X coordinate
252
 * @param y - Y coordinate
253
 * @return 0 on success, 1 on failure
254
 */
255
int ptaAddPt(PTA pta, float x, float y);
256

257
/**
258
 * Get point from array
259
 * @param pta - Source array
260
 * @param index - Point index
261
 * @param px - Returns x coordinate
262
 * @param py - Returns y coordinate
263
 * @return 0 on success, 1 on failure
264
 */
265
int ptaGetPt(PTA pta, int index, FloatPointer px, FloatPointer py);
266

267
/**
268
 * Get number of points
269
 * @param pta - Source array
270
 * @return Number of points
271
 */
272
int ptaGetCount(PTA pta);
273

274
/**
275
 * Get bounding box of all points
276
 * @param pta - Source array
277
 * @param pminx - Returns minimum x (can be null)
278
 * @param pmaxx - Returns maximum x (can be null)
279
 * @param pminy - Returns minimum y (can be null)
280
 * @param pmaxy - Returns maximum y (can be null)
281
 * @return 0 on success, 1 on failure
282
 */
283
int ptaGetRange(PTA pta, FloatPointer pminx, FloatPointer pmaxx, FloatPointer pminy, FloatPointer pmaxy);
284

285
/**
286
 * Linear least squares fit to points
287
 * @param pta - Source points
288
 * @param pa - Returns slope coefficient
289
 * @param pb - Returns intercept coefficient
290
 * @param pnafit - Returns fitted points (can be null)
291
 * @param ppixplot - Returns plot image (can be null)
292
 * @return 0 on success, 1 on failure
293
 */
294
int ptaGetLinearLSF(PTA pta, FloatPointer pa, FloatPointer pb, NUMA nafit, PIX pixplot);
295

296
/**
297
 * Quadratic least squares fit
298
 * @param pta - Source points
299
 * @param pa - Returns x² coefficient
300
 * @param pb - Returns x coefficient  
301
 * @param pc - Returns constant coefficient
302
 * @param pnafit - Returns fitted points (can be null)  
303
 * @param ppixplot - Returns plot image (can be null)
304
 * @return 0 on success, 1 on failure
305
 */
306
int ptaGetQuadraticLSF(PTA pta, FloatPointer pa, FloatPointer pb, FloatPointer pc, NUMA nafit, PIX pixplot);
307
```
308

309
**Usage Examples:**
310

311
```java
312
// Create point array for curve fitting
313
PTA points = ptaCreate(20);
314

315
// Add sample points (e.g., from edge detection)
316
ptaAddPt(points, 10.0f, 15.2f);
317
ptaAddPt(points, 20.0f, 25.1f);
318
ptaAddPt(points, 30.0f, 35.8f);
319
ptaAddPt(points, 40.0f, 44.9f);
320

321
// Fit linear model: y = ax + b
322
FloatPointer slope = new FloatPointer(1);
323
FloatPointer intercept = new FloatPointer(1);
324
int result = ptaGetLinearLSF(points, slope, intercept, null, null);
325
if (result == 0) {
326
    System.out.println("Line: y = " + slope.get() + "x + " + intercept.get());
327
}
328

329
// Get point range for normalization
330
FloatPointer minx = new FloatPointer(1);
331
FloatPointer maxx = new FloatPointer(1);
332
FloatPointer miny = new FloatPointer(1);
333
FloatPointer maxy = new FloatPointer(1);
334
ptaGetRange(points, minx, maxx, miny, maxy);
335

336
// Access individual points
337
int count = ptaGetCount(points);
338
for (int i = 0; i < count; i++) {
339
    FloatPointer x = new FloatPointer(1);
340
    FloatPointer y = new FloatPointer(1);
341
    ptaGetPt(points, i, x, y);
342
    System.out.println("Point " + i + ": (" + x.get() + ", " + y.get() + ")");
343
}
344
```
345

346
### Geometric Calculations
347

348
Utility functions for geometric calculations and spatial analysis.
349

350
```java { .api }
351
/**
352
 * Calculate distance between two points
353
 * @param x1 - First point x coordinate
354
 * @param y1 - First point y coordinate
355
 * @param x2 - Second point x coordinate  
356
 * @param y2 - Second point y coordinate
357
 * @return Distance between points
358
 */
359
float l_distancePointToPoint(float x1, float y1, float x2, float y2);
360

361
/**
362
 * Calculate distance from point to line
363
 * @param x - Point x coordinate
364
 * @param y - Point y coordinate
365
 * @param a - Line slope coefficient
366
 * @param b - Line intercept coefficient
367
 * @return Distance from point to line
368
 */
369
float l_distancePointToLine(float x, float y, float a, float b);
370

371
/**
372
 * Check if point is on line within tolerance
373
 * @param x - Point x coordinate
374
 * @param y - Point y coordinate  
375
 * @param a - Line slope coefficient
376
 * @param b - Line intercept coefficient
377
 * @param dist - Distance tolerance
378
 * @param presult - Returns 1 if on line, 0 otherwise
379
 * @return 0 on success, 1 on failure
380
 */
381
int l_isPointOnLine(float x, float y, float a, float b, float dist, IntPointer presult);
382

383
/**
384
 * Find intersection of two lines
385
 * @param a1 - First line slope
386
 * @param b1 - First line intercept
387
 * @param a2 - Second line slope
388
 * @param b2 - Second line intercept
389
 * @param px - Returns intersection x coordinate
390
 * @param py - Returns intersection y coordinate
391
 * @return 0 on success, 1 if lines are parallel
392
 */
393
int l_getIntersectionOfLines(float a1, float b1, float a2, float b2, FloatPointer px, FloatPointer py);
394
```
395

396
**Usage Examples:**
397

398
```java
399
// Calculate distance between two detected features
400
float distance = l_distancePointToPoint(100.0f, 200.0f, 300.0f, 150.0f);
401
System.out.println("Feature distance: " + distance + " pixels");
402

403
// Check if point lies on fitted line
404
FloatPointer onLine = new IntPointer(1);
405
l_isPointOnLine(150.0f, 175.0f, 1.2f, 25.0f, 5.0f, onLine);
406
if (onLine.get() == 1) {
407
    System.out.println("Point is on the line");
408
}
409

410
// Find intersection of two lines
411
FloatPointer intersectX = new FloatPointer(1);
412
FloatPointer intersectY = new FloatPointer(1);
413
int intersects = l_getIntersectionOfLines(1.0f, 0.0f, -1.0f, 200.0f, intersectX, intersectY);
414
if (intersects == 0) {
415
    System.out.println("Lines intersect at: (" + intersectX.get() + ", " + intersectY.get() + ")");
416
}
417
```
418

419
## Geometric Constants
420

421
```java { .api }
422
// Copy/access flags
423
static final int L_COPY = 0;
424
static final int L_CLONE = 1;
425
static final int L_INSERT = 2;
426

427
// Sort criteria for boxes
428
static final int L_SORT_BY_X = 1;
429
static final int L_SORT_BY_Y = 2;
430
static final int L_SORT_BY_WIDTH = 3;
431
static final int L_SORT_BY_HEIGHT = 4;
432
static final int L_SORT_BY_AREA = 5;
433
static final int L_SORT_BY_PERIMETER = 6;
434

435
// Sort orders
436
static final int L_SORT_INCREASING = 1;
437
static final int L_SORT_DECREASING = 2;
438
```
439

440
## Common Use Cases
441

442
### Region of Interest Processing
443
```java
444
// Define ROI and extract for processing  
445
BOX roi = boxCreate(x, y, width, height);
446
PIX region = pixClipRectangle(image, roi, null);
447
PIX processed = pixGaussianBlur(region, 2.0f, 2.0f);
448
```
449

450
### Multi-Region Analysis
451
```java
452
// Process multiple detected regions
453
BOXA detections = detectObjects(image); // hypothetical function
454
int count = boxaGetCount(detections);
455
for (int i = 0; i < count; i++) {
456
    BOX box = boxaGetBox(detections, i, L_CLONE);
457
    PIX object = pixClipRectangle(image, box, null);
458
    // Analyze object...
459
}
460
```
461

462
### Curve Fitting
463
```java  
464
// Fit curve to edge points
465
PTA edgePoints = extractEdgePoints(image); // hypothetical function
466
FloatPointer a = new FloatPointer(1);
467
FloatPointer b = new FloatPointer(1);
468
FloatPointer c = new FloatPointer(1);
469
ptaGetQuadraticLSF(edgePoints, a, b, c, null, null);
470
```