0
# Result Analysis with Iterators
1

2
Detailed analysis of OCR results using iterator classes that provide hierarchical navigation through page structure, word-level confidence scores, bounding boxes, font information, and alternative recognition choices.
3

4
## Capabilities
5

6
### ResultIterator Class
7

8
Primary iterator for OCR results that handles proper reading order and bidirectional text correctly.
9

10
```java { .api }
11
/**
12
 * Iterator for OCR results in proper reading order
13
 * Handles bidirectional text correctly and provides access to recognition results
14
 */
15
public class ResultIterator extends LTRResultIterator {
16
    // Navigation methods
17
    public void Begin();
18
    public boolean Next(int level);
19
    public boolean IsAtBeginningOf(int level);
20
    public boolean IsAtFinalElement(int level, int element);
21
    
22
    // Text access
23
    public BytePointer GetUTF8Text(int level);
24
    public int BlanksBeforeWord();
25
    public boolean ParagraphIsLtr();
26
    
27
    // LSTM support  
28
    public StringFloatPairVectorVector GetRawLSTMTimesteps();
29
    public StringFloatPairVectorVector GetBestLSTMSymbolChoices();
30
}
31
```
32

33
**Detailed Analysis Example:**
34

35
```java
36
import org.bytedeco.tesseract.*;
37
import static org.bytedeco.tesseract.global.tesseract.*;
38

39
// Get results iterator
40
ResultIterator ri = api.GetIterator();
41
int level = RIL_WORD;
42

43
if (ri != null) {
44
    do {
45
        // Get word text and confidence
46
        BytePointer word = ri.GetUTF8Text(level);
47
        float conf = ri.Confidence(level);
48
        
49
        // Get bounding box
50
        int[] x1 = new int[1], y1 = new int[1], x2 = new int[1], y2 = new int[1];
51
        ri.BoundingBox(level, x1, y1, x2, y2);
52
        
53
        // Get font information
54
        boolean[] isBold = new boolean[1], isItalic = new boolean[1];
55
        boolean[] isUnderlined = new boolean[1], isMonospace = new boolean[1];
56
        boolean[] isSerif = new boolean[1], isSmallcaps = new boolean[1];
57
        int[] pointsize = new int[1], fontId = new int[1];
58
        
59
        String fontName = ri.WordFontAttributes(isBold, isItalic, isUnderlined, 
60
                                               isMonospace, isSerif, isSmallcaps, 
61
                                               pointsize, fontId);
62
        
63
        System.out.printf("Word: '%s' | Confidence: %.2f%% | Box: (%d,%d,%d,%d) | Font: %s %dpt%n",
64
                         word.getString(), conf, x1[0], y1[0], x2[0], y2[0], 
65
                         fontName, pointsize[0]);
66
        
67
        word.deallocate();
68
    } while (ri.Next(level));
69
}
70
```
71

72
### PageIterator Class  
73

74
Base iterator for page structure hierarchy providing layout analysis without OCR results.
75

76
```java { .api }
77
/**
78
 * Iterator for page structure hierarchy without OCR results
79
 * Provides access to layout analysis and page structure
80
 */
81
public class PageIterator extends Pointer {
82
    // Navigation
83
    public void Begin();
84
    public boolean Next(int level);
85
    public void RestartParagraph();
86
    public void RestartRow();
87
    public boolean IsAtBeginningOf(int level);
88
    public boolean IsAtFinalElement(int level, int element);
89
    
90
    // Bounding boxes
91
    public boolean BoundingBox(int level, IntPointer left, IntPointer top, 
92
                              IntPointer right, IntPointer bottom);
93
    public void SetBoundingBoxComponents(boolean include_upper_dots, boolean include_lower_dots);
94
    
95
    // Content access
96
    public int BlockType();
97
    public PTA BlockPolygon();
98
    public PIX GetBinaryImage(int level);
99
    public PIX GetImage(int level, int padding, PIX original_img, 
100
                       IntPointer left, IntPointer top);
101
    public boolean Baseline(int level, IntPointer x1, IntPointer y1, 
102
                           IntPointer x2, IntPointer y2);
103
    
104
    // Text properties
105
    public void Orientation(IntPointer orientation, IntPointer writing_direction,
106
                           IntPointer textline_order, FloatPointer deskew_angle);
107
    public void ParagraphInfo(IntPointer justification, BoolPointer is_list_item,
108
                             BoolPointer is_crown, IntPointer first_line_indent); 
109
}
110
```
111

112
### LTRResultIterator Class
113

114
Left-to-right result iterator providing text-specific methods and font information.
115

116
```java { .api }
117
/**
118
 * Left-to-right result iterator with text-specific methods
119
 * Base class for ResultIterator with detailed text analysis capabilities
120
 */
121
public class LTRResultIterator extends PageIterator {
122
    // Text output
123
    public BytePointer GetUTF8Text(int level);
124
    public void SetLineSeparator(String new_line);
125
    public void SetParagraphSeparator(String new_para);
126
    public float Confidence(int level);
127
    
128
    // Font information
129
    public String WordFontAttributes(boolean[] is_bold, boolean[] is_italic,
130
                                   boolean[] is_underlined, boolean[] is_monospace,
131
                                   boolean[] is_serif, boolean[] is_smallcaps,
132
                                   IntBuffer pointsize, IntBuffer font_id);
133
    public String WordRecognitionLanguage();
134
    public int WordDirection();
135
    
136
    // Word properties
137
    public boolean WordIsFromDictionary();
138
    public boolean WordIsNumeric();
139
    public int BlanksBeforeWord();
140
    
141
    // Symbol properties
142
    public boolean SymbolIsSuperscript();
143
    public boolean SymbolIsSubscript();
144
    public boolean SymbolIsDropcap();
145
}
146
```
147

148
### ChoiceIterator Class
149

150
Iterator for examining alternative recognition choices for a single symbol.
151

152
```java { .api }
153
/**
154
 * Iterator over classifier choices for a single symbol
155
 * Provides access to alternative recognition results with confidence scores
156
 */
157
public class ChoiceIterator extends Pointer {
158
    /**
159
     * Create choice iterator from result iterator position
160
     * @param result_it Result iterator positioned at symbol
161
     */
162
    public ChoiceIterator(LTRResultIterator result_it);
163
    
164
    /**
165
     * Move to next choice for current symbol
166
     * @return true if more choices available
167
     */
168
    public boolean Next();
169
    
170
    /**
171
     * Get text of current choice (do not deallocate)
172
     * @return Choice text as BytePointer
173
     */
174
    public BytePointer GetUTF8Text();
175
    
176
    /**
177
     * Get confidence score for current choice
178
     * @return Confidence percentage (0-100)
179
     */
180
    public float Confidence();
181
    
182
    /**
183
     * Get LSTM timesteps for current choice
184
     * @return Complex timestep data structure
185
     */
186
    public StringFloatPairVectorVector Timesteps();
187
}
188
```
189

190
**Alternative Choices Example:**
191

192
```java
193
// Position iterator at a specific symbol
194
ResultIterator ri = api.GetIterator();
195
ri.Begin();
196

197
// Get choices for current symbol
198
ChoiceIterator ci = new ChoiceIterator(ri);
199
if (ci != null) {
200
    do {
201
        BytePointer choice = ci.GetUTF8Text();
202
        float conf = ci.Confidence();
203
        System.out.printf("Choice: '%s' (%.2f%%)%n", choice.getString(), conf);
204
        // Note: choice text should not be deallocated
205
    } while (ci.Next());
206
}
207
```
208

209
## Iterator Level Constants
210

211
Navigation and analysis can be performed at different hierarchical levels:
212

213
```java { .api }
214
// Page Iterator Level Constants
215
public static final int RIL_BLOCK = 0;      // Block level (paragraphs, images, etc.)
216
public static final int RIL_PARA = 1;       // Paragraph level
217
public static final int RIL_TEXTLINE = 2;   // Text line level  
218
public static final int RIL_WORD = 3;       // Word level
219
public static final int RIL_SYMBOL = 4;     // Symbol/character level
220
```
221

222
**Hierarchical Navigation Example:**
223

224
```java
225
ResultIterator ri = api.GetIterator();
226

227
// Iterate through paragraphs
228
ri.Begin();
229
do {
230
    System.out.println("=== PARAGRAPH ===");
231
    BytePointer para = ri.GetUTF8Text(RIL_PARA);
232
    System.out.println("Paragraph: " + para.getString());
233
    para.deallocate();
234
    
235
    // Iterate through words in this paragraph
236
    do {
237
        BytePointer word = ri.GetUTF8Text(RIL_WORD);
238
        float conf = ri.Confidence(RIL_WORD);
239
        System.out.printf("  Word: '%s' (%.1f%%)%n", word.getString(), conf);
240
        word.deallocate();
241
    } while (ri.Next(RIL_WORD) && !ri.IsAtBeginningOf(RIL_PARA));
242
    
243
} while (ri.Next(RIL_PARA));
244
```
245

246
## Font and Style Information
247

248
Detailed font attributes available through iterator methods:
249

250
```java { .api }
251
/**
252
 * Get comprehensive font attributes for current word
253
 * @param is_bold Output: true if font is bold
254
 * @param is_italic Output: true if font is italic  
255
 * @param is_underlined Output: true if text is underlined
256
 * @param is_monospace Output: true if font is monospace
257
 * @param is_serif Output: true if font has serifs
258
 * @param is_smallcaps Output: true if text is small caps
259
 * @param pointsize Output: font size in points
260
 * @param font_id Output: internal font identifier
261
 * @return Font family name
262
 */
263
public String WordFontAttributes(boolean[] is_bold, boolean[] is_italic,
264
                               boolean[] is_underlined, boolean[] is_monospace,
265
                               boolean[] is_serif, boolean[] is_smallcaps,
266
                               IntBuffer pointsize, IntBuffer font_id);
267
```
268

269
**Font Analysis Example:**
270

271
```java
272
ResultIterator ri = api.GetIterator();
273
ri.Begin();
274

275
do {
276
    BytePointer word = ri.GetUTF8Text(RIL_WORD);
277
    
278
    // Get font attributes
279
    boolean[] bold = new boolean[1], italic = new boolean[1];
280
    boolean[] underlined = new boolean[1], monospace = new boolean[1];
281
    boolean[] serif = new boolean[1], smallcaps = new boolean[1];
282
    int[] size = new int[1], fontId = new int[1];
283
    
284
    String fontFamily = ri.WordFontAttributes(bold, italic, underlined, 
285
                                             monospace, serif, smallcaps,
286
                                             size, fontId);
287
    
288
    // Build style description
289
    StringBuilder style = new StringBuilder();
290
    if (bold[0]) style.append("Bold ");
291
    if (italic[0]) style.append("Italic ");
292
    if (underlined[0]) style.append("Underlined ");
293
    if (smallcaps[0]) style.append("SmallCaps ");
294
    
295
    System.out.printf("'%s' - %s %dpt %s%n", 
296
                     word.getString(), fontFamily, size[0], style.toString());
297
    
298
    word.deallocate();
299
} while (ri.Next(RIL_WORD));
300
```
301

302
## Text Properties and Metadata
303

304
Additional text analysis capabilities:
305

306
```java { .api }
307
// Word classification
308
public boolean WordIsFromDictionary();       // Word found in dictionary
309
public boolean WordIsNumeric();              // Word contains only numbers  
310
public int WordDirection();                  // Text direction (LTR/RTL)
311
public String WordRecognitionLanguage();     // Detected language
312

313
// Symbol properties
314
public boolean SymbolIsSuperscript();        // Symbol is superscript
315
public boolean SymbolIsSubscript();          // Symbol is subscript  
316
public boolean SymbolIsDropcap();            // Symbol is drop capital
317

318
// Layout properties
319
public int BlanksBeforeWord();              // Number of spaces before word
320
public boolean ParagraphIsLtr();            // Paragraph is left-to-right
321
```
322

323
## Bounding Box Information
324

325
Get precise coordinate information for layout analysis:
326

327
```java { .api }
328
/**
329
 * Get bounding rectangle for element at specified level
330
 * @param level Iterator level (RIL_BLOCK, RIL_PARA, RIL_TEXTLINE, RIL_WORD, RIL_SYMBOL)
331
 * @param left Output: left coordinate
332
 * @param top Output: top coordinate  
333
 * @param right Output: right coordinate
334
 * @param bottom Output: bottom coordinate
335
 * @return true if bounding box is available
336
 */
337
public boolean BoundingBox(int level, IntPointer left, IntPointer top,
338
                          IntPointer right, IntPointer bottom);
339

340
/**
341
 * Get baseline coordinates for text line
342
 * @param level Iterator level
343
 * @param x1 Output: baseline start X
344
 * @param y1 Output: baseline start Y
345
 * @param x2 Output: baseline end X  
346
 * @param y2 Output: baseline end Y
347
 * @return true if baseline is available
348
 */
349
public boolean Baseline(int level, IntPointer x1, IntPointer y1,
350
                       IntPointer x2, IntPointer y2);
351
```
352

353
**Layout Analysis Example:**
354

355
```java
356
PageIterator pi = api.AnalyseLayout();  // Layout analysis without OCR
357
pi.Begin();
358

359
do {
360
    int blockType = pi.BlockType();
361
    System.out.println("Block Type: " + getBlockTypeName(blockType));
362
    
363
    // Get block bounding box
364
    int[] left = new int[1], top = new int[1];
365
    int[] right = new int[1], bottom = new int[1];
366
    if (pi.BoundingBox(RIL_BLOCK, left, top, right, bottom)) {
367
        System.out.printf("Block bounds: (%d,%d) to (%d,%d)%n", 
368
                         left[0], top[0], right[0], bottom[0]);
369
    }
370
    
371
    // Get orientation information
372
    int[] orientation = new int[1], writingDir = new int[1];
373
    int[] textlineOrder = new int[1];
374
    float[] deskewAngle = new float[1];
375
    pi.Orientation(orientation, writingDir, textlineOrder, deskewAngle);
376
    
377
    System.out.printf("Orientation: %d°, Writing Direction: %s%n",
378
                     orientation[0] * 90, getWritingDirection(writingDir[0]));
379
    
380
} while (pi.Next(RIL_BLOCK));
381
```
382

383
## Memory Management
384

385
**Important Iterator Guidelines:**
386
- Iterators are automatically managed by JavaCPP
387
- Always call `deallocate()` on BytePointer results from `GetUTF8Text()`
388
- Check for null before using iterators
389
- ChoiceIterator text results should NOT be deallocated
390
- Iterators become invalid after calling `api.End()`