0
# Result Navigation
1

2
Hierarchical iterators for navigating OCR results from page structure down to individual characters. The iterator hierarchy provides access to bounding boxes, confidence scores, text formatting, and detailed layout information at multiple levels of granularity.
3

4
## Capabilities
5

6
### Iterator Hierarchy
7

8
The iterator classes form a hierarchy that provides increasingly detailed access to recognition results:
9

10
```java { .api }
11
// Base iterator for page structure (no OCR text access)
12
public class PageIterator {
13
    // Navigation
14
    public void Begin();
15
    public boolean Next(int level);
16
    public void RestartParagraph();
17
    public void RestartRow();
18
    
19
    // Position queries
20
    public boolean IsAtBeginningOf(int level);
21
    public boolean IsAtFinalElement(int level, int element);
22
    public boolean Empty(int level);
23
}
24

25
// Adds OCR text access (extends PageIterator)
26
public class LTRResultIterator extends PageIterator {
27
    public native @Cast("char*") BytePointer GetUTF8Text(int level);
28
    public float Confidence(int level);
29
    public void SetLineSeparator(String new_line);
30
    public void SetParagraphSeparator(String new_para);
31
}
32

33
// Adds bidirectional text support (extends LTRResultIterator)  
34
public class ResultIterator extends LTRResultIterator {
35
    public boolean ParagraphIsLtr();
36
    public StringFloatPairVectorVector GetRawLSTMTimesteps();
37
    public StringFloatPairVectorVector GetBestLSTMSymbolChoices();
38
}
39
```
40

41
**Iterator Levels:**
42
- `RIL_BLOCK` (0): Text blocks, images, tables
43
- `RIL_PARA` (1): Paragraphs within blocks
44
- `RIL_TEXTLINE` (2): Lines within paragraphs
45
- `RIL_WORD` (3): Words within lines
46
- `RIL_SYMBOL` (4): Characters within words
47

48
### Basic Navigation
49

50
Navigate through the page hierarchy and access structural information.
51

52
```java { .api }
53
public class PageIterator {
54
    // Movement
55
    public void Begin();                           // Move to start of page
56
    public boolean Next(int level);               // Move to next element at level
57
    public void RestartParagraph();               // Move to paragraph start
58
    public void RestartRow();                     // Move to row start
59
    
60
    // Position testing
61
    public boolean IsAtBeginningOf(int level);    // Check if at beginning
62
    public boolean IsAtFinalElement(int level, int element);
63
    public boolean Empty(int level);              // Check if level is empty
64
}
65
```
66

67
#### Usage Example
68

69
```java
70
TessBaseAPI api = new TessBaseAPI();
71
api.Init(null, "eng");
72
api.SetImage(image);
73

74
PageIterator pageIt = api.AnalyseLayout();
75
if (pageIt != null) {
76
    pageIt.Begin();
77
    
78
    // Iterate through all text blocks
79
    do {
80
        int blockType = pageIt.BlockType();
81
        System.out.println("Block type: " + blockType);
82
        
83
        // Get block bounding box
84
        int[] left = new int[1], top = new int[1], 
85
              right = new int[1], bottom = new int[1];
86
        if (pageIt.BoundingBox(RIL_BLOCK, left, top, right, bottom)) {
87
            System.out.println("Block bounds: " + left[0] + "," + top[0] + 
88
                             " to " + right[0] + "," + bottom[0]);
89
        }
90
        
91
    } while (pageIt.Next(RIL_BLOCK));
92
}
93
```
94

95
### Bounding Boxes and Geometry
96

97
Access precise coordinate information for layout elements.
98

99
```java { .api }
100
public class PageIterator {
101
    // Bounding rectangles
102
    public boolean BoundingBox(int level, int[] left, int[] top, 
103
                              int[] right, int[] bottom);
104
    
105
    // Text baselines  
106
    public boolean Baseline(int level, int[] x1, int[] y1, int[] x2, int[] y2);
107
    
108
    // Orientation information
109
    public void Orientation(int[] orientation, int[] writing_direction,
110
                           int[] textline_order, float[] deskew_angle);
111
    
112
    // Block outline polygon
113
    public PTA BlockPolygon();
114
}
115
```
116

117
**Coordinate System:**
118
- Origin (0,0) at top-left of image
119
- X increases rightward, Y increases downward
120
- All coordinates in pixels
121

122
#### Usage Example
123

124
```java
125
ResultIterator resultIt = api.GetIterator();
126
resultIt.Begin();
127

128
// Get coordinates for all words
129
do {
130
    int[] left = new int[1], top = new int[1], 
131
          right = new int[1], bottom = new int[1];
132
    
133
    if (resultIt.BoundingBox(RIL_WORD, left, top, right, bottom)) {
134
        String word = resultIt.GetUTF8Text(RIL_WORD);
135
        float confidence = resultIt.Confidence(RIL_WORD);
136
        
137
        System.out.printf("Word: '%s' at (%d,%d)-(%d,%d) conf=%.1f%%\n",
138
                         word, left[0], top[0], right[0], bottom[0], confidence);
139
    }
140
    
141
} while (resultIt.Next(RIL_WORD));
142
```
143

144
### Text Extraction with Formatting
145

146
Extract text content with detailed formatting and style information.
147

148
```java { .api }
149
public class LTRResultIterator {
150
    // Text extraction
151
    public native @Cast("char*") BytePointer GetUTF8Text(int level);
152
    
153
    // Text separators
154
    public void SetLineSeparator(String new_line);
155
    public void SetParagraphSeparator(String new_para);
156
    
157
    // Font and style information
158
    public String WordFontAttributes(boolean[] is_bold, boolean[] is_italic,
159
                                   boolean[] is_underlined, boolean[] is_monospace, 
160
                                   boolean[] is_serif, boolean[] is_smallcaps,
161
                                   int[] pointsize, int[] font_id);
162
    
163
    // Language and dictionary information
164
    public String WordRecognitionLanguage();
165
    public boolean WordIsFromDictionary();
166
    public boolean WordIsNumeric();
167
    public int WordDirection();
168
    public int BlanksBeforeWord();
169
}
170
```
171

172
#### Usage Example
173

174
```java
175
ResultIterator it = api.GetIterator();
176
it.Begin();
177

178
// Extract formatted text information
179
do {
180
    String word = it.GetUTF8Text(RIL_WORD);
181
    float conf = it.Confidence(RIL_WORD);
182
    
183
    // Get font styling
184
    boolean[] bold = new boolean[1], italic = new boolean[1], 
185
              underlined = new boolean[1], monospace = new boolean[1],
186
              serif = new boolean[1], smallcaps = new boolean[1];
187
    int[] pointsize = new int[1], font_id = new int[1];
188
    
189
    String fontName = it.WordFontAttributes(bold, italic, underlined, 
190
                                          monospace, serif, smallcaps, 
191
                                          pointsize, font_id);
192
    
193
    System.out.printf("Word: '%s' Font: %s Size: %dpt Bold: %s Italic: %s\n",
194
                     word, fontName, pointsize[0], bold[0], italic[0]);
195
    
196
    // Check word properties
197
    if (it.WordIsNumeric()) {
198
        System.out.println("  -> Numeric word");
199
    }
200
    if (it.WordIsFromDictionary()) {
201
        System.out.println("  -> Dictionary word");
202
    }
203
    
204
} while (it.Next(RIL_WORD));
205
```
206

207
### Character-Level Analysis
208

209
Access individual character information including superscripts, subscripts, and detailed symbol properties.
210

211
```java { .api }
212
public class LTRResultIterator {
213
    // Symbol properties
214
    public boolean SymbolIsSuperscript();
215
    public boolean SymbolIsSubscript();
216
    public boolean SymbolIsDropcap();
217
}
218
```
219

220
#### Usage Example
221

222
```java
223
ResultIterator it = api.GetIterator();
224
it.Begin();
225

226
// Analyze character-level details
227
do {
228
    String symbol = it.GetUTF8Text(RIL_SYMBOL);
229
    float conf = it.Confidence(RIL_SYMBOL);
230
    
231
    System.out.printf("Symbol: '%s' conf=%.1f%%", symbol, conf);
232
    
233
    if (it.SymbolIsSuperscript()) {
234
        System.out.print(" [SUPERSCRIPT]");
235
    }
236
    if (it.SymbolIsSubscript()) {
237
        System.out.print(" [SUBSCRIPT]");
238
    }
239
    if (it.SymbolIsDropcap()) {
240
        System.out.print(" [DROPCAP]");
241
    }
242
    
243
    System.out.println();
244
    
245
} while (it.Next(RIL_SYMBOL));
246
```
247

248
### Bidirectional Text Support
249

250
Handle complex scripts with mixed text directions and reading orders.
251

252
```java { .api }
253
public class ResultIterator {
254
    // Text direction
255
    public boolean ParagraphIsLtr();
256
    
257
    // Reading order calculation
258
    public static void CalculateTextlineOrder(boolean paragraph_is_ltr, 
259
                                            int[] word_dirs, 
260
                                            int[] reading_order);
261
    
262
    // Advanced LSTM outputs
263
    public StringFloatPairVectorVector GetRawLSTMTimesteps();
264
    public StringFloatPairVectorVector GetBestLSTMSymbolChoices();
265
}
266
```
267

268
**Text Direction Constants:**
269
- `DIR_NEUTRAL` (0): Neutral characters
270
- `DIR_LEFT_TO_RIGHT` (1): LTR text (Latin, Cyrillic, etc.)
271
- `DIR_RIGHT_TO_LEFT` (2): RTL text (Arabic, Hebrew, etc.)
272
- `DIR_MIX` (3): Mixed direction text
273

274
#### Usage Example
275

276
```java
277
ResultIterator it = api.GetIterator();
278
it.Begin();
279

280
// Handle bidirectional text
281
do {
282
    if (it.IsAtBeginningOf(RIL_PARA)) {
283
        boolean isLtr = it.ParagraphIsLtr();
284
        System.out.println("Paragraph direction: " + 
285
                         (isLtr ? "Left-to-Right" : "Right-to-Left"));
286
    }
287
    
288
    String word = it.GetUTF8Text(RIL_WORD);
289
    int direction = it.WordDirection();
290
    
291
    System.out.printf("Word: '%s' Direction: %d\n", word, direction);
292
    
293
} while (it.Next(RIL_WORD));
294
```
295

296
### Alternative Recognition Choices
297

298
Access multiple recognition candidates for improved accuracy.
299

300
```java { .api }
301
public class ChoiceIterator {
302
    // Constructor from result iterator
303
    public ChoiceIterator(LTRResultIterator result_it);
304
    
305
    // Navigation
306
    public boolean Next();
307
    
308
    // Choice information
309
    public String GetUTF8Text();
310
    public float Confidence();
311
    public StringFloatPairVectorVector Timesteps();
312
}
313
```
314

315
#### Usage Example
316

317
```java
318
ResultIterator resultIt = api.GetIterator();
319
resultIt.Begin();
320

321
// Get alternative recognition choices for each symbol
322
do {
323
    String mainChoice = resultIt.GetUTF8Text(RIL_SYMBOL);
324
    float mainConf = resultIt.Confidence(RIL_SYMBOL);
325
    
326
    System.out.printf("Main choice: '%s' (%.1f%%)\n", mainChoice, mainConf);
327
    
328
    // Get alternatives
329
    ChoiceIterator choiceIt = new ChoiceIterator(resultIt);
330
    int choiceNum = 1;
331
    
332
    while (choiceIt.Next()) {
333
        String altChoice = choiceIt.GetUTF8Text();
334
        float altConf = choiceIt.Confidence();
335
        System.out.printf("  Alt %d: '%s' (%.1f%%)\n", 
336
                         choiceNum++, altChoice, altConf);
337
    }
338
    
339
} while (resultIt.Next(RIL_SYMBOL));
340
```
341

342
### Layout Structure Information
343

344
Access detailed page layout and block type information.
345

346
```java { .api }
347
public class PageIterator {
348
    // Block classification
349
    public int BlockType();
350
    
351
    // Paragraph information  
352
    public void ParagraphInfo(int[] justification, boolean[] is_list_item,
353
                             boolean[] is_crown, int[] first_line_indent);
354
    
355
    // Image extraction
356
    public PIX GetBinaryImage(int level);
357
    public PIX GetImage(int level, int padding, PIX original_img, 
358
                       int[] left, int[] top);
359
}
360
```
361

362
**Block Types:**
363
- `PT_FLOWING_TEXT` (1): Regular paragraph text
364
- `PT_HEADING_TEXT` (2): Heading or title text
365
- `PT_PULLOUT_TEXT` (3): Pull-quote or sidebar text
366
- `PT_EQUATION` (4): Mathematical equation
367
- `PT_TABLE` (6): Table structure
368
- `PT_VERTICAL_TEXT` (7): Vertical text orientation
369
- `PT_CAPTION_TEXT` (8): Image or table caption
370

371
#### Usage Example
372

373
```java
374
PageIterator pageIt = api.AnalyseLayout();
375
pageIt.Begin();
376

377
do {
378
    int blockType = pageIt.BlockType();
379
    String typeName = getBlockTypeName(blockType);
380
    System.out.println("Block type: " + typeName);
381
    
382
    if (blockType == PT_FLOWING_TEXT) {
383
        // Get paragraph details
384
        int[] justification = new int[1];
385
        boolean[] is_list = new boolean[1], is_crown = new boolean[1];
386
        int[] indent = new int[1];
387
        
388
        pageIt.ParagraphInfo(justification, is_list, is_crown, indent);
389
        
390
        System.out.println("  Justification: " + justification[0]);
391
        System.out.println("  List item: " + is_list[0]);
392
        System.out.println("  First line indent: " + indent[0]);
393
    }
394
    
395
} while (pageIt.Next(RIL_BLOCK));
396
```
397

398
## Types
399

400
### Iterator Level Constants
401

402
```java { .api }
403
public static final int RIL_BLOCK = 0;     // Block level
404
public static final int RIL_PARA = 1;      // Paragraph level
405
public static final int RIL_TEXTLINE = 2;  // Text line level
406
public static final int RIL_WORD = 3;      // Word level
407
public static final int RIL_SYMBOL = 4;    // Character/symbol level
408
```
409

410
### Text Direction Constants
411

412
```java { .api }
413
public static final int DIR_NEUTRAL = 0;        // Neutral text
414
public static final int DIR_LEFT_TO_RIGHT = 1;  // LTR text
415
public static final int DIR_RIGHT_TO_LEFT = 2;  // RTL text
416
public static final int DIR_MIX = 3;            // Mixed direction
417
```
418

419
### Advanced Data Structures
420

421
```java { .api }
422
// Vector of string-float pairs for LSTM outputs
423
public class StringFloatPairVectorVector {
424
    public long size();
425
    // Contains timestep information and confidence scores
426
    // for neural network recognition alternatives
427
}
428

429
// Mutable iterator for result modification (opaque)
430
public class MutableIterator {
431
    // Allows modification of recognition results
432
    // Internal implementation details not exposed
433
}
434
```