0
# Data Structures and Types
1

2
Supporting data types for progress monitoring, character information, Unicode handling, container classes, and callback functions used throughout the Tesseract API.
3

4
## Capabilities
5

6
### Progress Monitoring
7

8
Structure for monitoring OCR progress and implementing cancellation callbacks.
9

10
```java { .api }
11
/**
12
 * Progress monitoring and cancellation structure for OCR operations
13
 * Provides real-time feedback and cancellation capability during recognition
14
 */
15
public class ETEXT_DESC extends Pointer {
16
    public ETEXT_DESC();
17
    
18
    // Progress information (read-only fields)
19
    public short count();              // Character count processed
20
    public short progress();           // Progress percentage (0-100)
21
    public byte more_to_come();        // More processing flag
22
    public byte ocr_alive();           // OCR engine alive flag  
23
    public byte err_code();            // Error code (0 = no error)
24
    
25
    // Callback functions
26
    public CANCEL_FUNC cancel();                    // Cancellation callback
27
    public PROGRESS_FUNC progress_callback();       // Progress callback
28
    public Pointer cancel_this();                   // Cancellation context
29
    
30
    // Character data access
31
    public EANYCODE_CHAR text(int i);              // Character data array
32
    
33
    // Deadline management
34
    public void set_deadline_msecs(int deadline_msecs); // Set processing deadline
35
    public boolean deadline_exceeded();                 // Check if deadline exceeded
36
}
37
```
38

39
**Progress Monitoring Example:**
40

41
```java
42
import org.bytedeco.tesseract.*;
43
import static org.bytedeco.tesseract.global.tesseract.*;
44

45
// Create progress monitor
46
ETEXT_DESC monitor = TessMonitorCreate();
47

48
// Set 30-second deadline
49
monitor.set_deadline_msecs(30000);
50

51
TessBaseAPI api = new TessBaseAPI();
52
api.Init(null, "eng");
53

54
PIX image = pixRead("large-document.png");
55
api.SetImage(image);
56

57
// Perform OCR with progress monitoring
58
int result = api.Recognize(monitor);
59

60
if (result == 0) {
61
    System.out.println("OCR completed successfully");
62
    System.out.println("Final progress: " + monitor.progress() + "%");
63
    System.out.println("Characters processed: " + monitor.count());
64
} else {
65
    System.err.println("OCR failed with error code: " + monitor.err_code());
66
    if (monitor.deadline_exceeded()) {
67
        System.err.println("Processing deadline exceeded");
68
    }
69
}
70

71
// Cleanup
72
TessMonitorDelete(monitor);
73
pixDestroy(image);
74
api.End();
75
```
76

77
### Character Information
78

79
Detailed character description with position, font, and formatting information.
80

81
```java { .api }
82
/**
83
 * Single character description with position, font, and formatting information
84
 * Used in ETEXT_DESC for detailed character-level analysis
85
 */
86
public class EANYCODE_CHAR extends Pointer {
87
    public EANYCODE_CHAR();
88
    
89
    // Character identification
90
    public short char_code();          // UTF-8 character code
91
    
92
    // Position information  
93
    public short left();               // Left coordinate
94
    public short right();              // Right coordinate
95
    public short top();                // Top coordinate
96
    public short bottom();             // Bottom coordinate
97
    
98
    // Font and style information
99
    public short font_index();         // Font identifier
100
    public byte point_size();          // Font size in points
101
    public byte formatting();          // Formatting flags (bold, italic, etc.)
102
    
103
    // Recognition quality
104
    public byte confidence();          // Confidence score (0=perfect, 100=reject)
105
    public byte blanks();              // Number of spaces before character
106
}
107
```
108

109
### Unicode Character Handling
110

111
Unicode character representation supporting UTF-8 encoding and ligatures.
112

113
```java { .api }
114
/**
115
 * Unicode character representation supporting UTF-8 encoding and ligatures
116
 * Handles complex Unicode characters and multi-byte sequences
117
 */
118
public class UNICHAR extends Pointer {
119
    public UNICHAR();
120
    public UNICHAR(String utf8_str, int len);
121
    public UNICHAR(int unicode);
122
    
123
    // Character access methods
124
    public int first_uni();            // Get first character as UCS-4
125
    public int utf8_len();             // Get UTF-8 byte length
126
    public BytePointer utf8();         // Get UTF-8 bytes (not null-terminated)
127
    public BytePointer utf8_str();     // Get terminated UTF-8 string (must delete)
128
    
129
    // Static utility methods
130
    public static int utf8_step(String utf8_str);                    // Get bytes in first character
131
    public static IntPointer UTF8ToUTF32(String utf8_str);           // Convert UTF-8 to UTF-32
132
    public static String UTF32ToUTF8(IntPointer str32);              // Convert UTF-32 to UTF-8
133
    
134
    // Nested iterator class for UTF-8 strings
135
    public static class const_iterator extends Pointer {
136
        public const_iterator increment();    // Step to next character
137
        public int multiply();                 // Get current UCS-4 value
138
        public int get_utf8(byte[] buf);       // Get UTF-8 bytes
139
        public boolean is_legal();             // Check if current position is legal UTF-8
140
    }
141
}
142
```
143

144
**Unicode Processing Example:**
145

146
```java
147
// Create UNICHAR from UTF-8 string
148
UNICHAR unichar = new UNICHAR("Hello 世界", 11);
149

150
System.out.println("UTF-8 length: " + unichar.utf8_len());
151
System.out.println("First character UCS-4: " + unichar.first_uni());
152

153
// Get terminated UTF-8 string
154
BytePointer utf8_str = unichar.utf8_str();
155
System.out.println("UTF-8 string: " + utf8_str.getString());
156
utf8_str.deallocate(); // Must delete UTF-8 string
157

158
// Iterate through UTF-8 string character by character
159
String text = "Café";
160
UNICHAR.const_iterator it = new UNICHAR.const_iterator();
161
// Iterator usage would require additional setup
162
```
163

164
### Container Classes
165

166
Vector containers for strings and other data types with Java-friendly interfaces.
167

168
```java { .api }
169
/**
170
 * Vector container for strings (std::vector<std::string>)
171
 * Provides Java-friendly interface to C++ string vectors
172
 */
173
public class StringVector extends Pointer {
174
    public StringVector();                      // Empty vector
175
    public StringVector(long n);                // Vector with n elements
176
    public StringVector(String value);          // Single string vector
177
    public StringVector(String... array);       // Vector from string array
178
    
179
    // Size management
180
    public long size();                         // Get size
181
    public boolean empty();                     // Check if empty
182
    public void clear();                        // Clear all elements
183
    public void resize(long n);                 // Resize vector
184
    
185
    // Element access
186
    public BytePointer get(long i);             // Get element at index
187
    public StringVector put(long i, String value);  // Set element at index
188
    public BytePointer front();                 // Get first element
189
    public BytePointer back();                  // Get last element
190
    
191
    // Modification
192
    public StringVector push_back(String value); // Add element to end
193
    public BytePointer pop_back();              // Remove and return last element
194
    public StringVector put(String... array);   // Set from array
195
}
196

197
/**
198
 * Vector container for bytes (std::vector<char>)
199
 * Similar interface to StringVector for byte data
200
 */
201
public class ByteVector extends Pointer {
202
    public ByteVector();
203
    public ByteVector(long n);
204
    public long size();
205
    public boolean empty();
206
    public void clear();
207
    public byte get(long i);
208
    public ByteVector put(long i, byte value);
209
    public ByteVector push_back(byte value);
210
}
211

212
/**
213
 * Complex nested vector structure for LSTM timestep data
214
 * Used for neural network output analysis
215
 */
216
public class StringFloatPairVectorVector extends Pointer {
217
    public StringFloatPairVectorVector();
218
    public long size();
219
    // Additional methods for LSTM-specific data manipulation
220
}
221
```
222

223
**Container Usage Examples:**
224

225
```java
226
// Create and populate string vector
227
StringVector languages = new StringVector();
228
languages.push_back("eng");
229
languages.push_back("fra");
230
languages.push_back("deu");
231

232
System.out.println("Languages count: " + languages.size());
233
for (int i = 0; i < languages.size(); i++) {
234
    System.out.println("Language " + i + ": " + languages.get(i).getString());
235
}
236

237
// Use with Tesseract API
238
TessBaseAPI api = new TessBaseAPI();
239
api.Init(null, "eng");
240

241
StringVector availableLanguages = new StringVector();
242
api.GetAvailableLanguagesAsVector(availableLanguages);
243

244
System.out.println("Available languages:");
245
for (int i = 0; i < availableLanguages.size(); i++) {
246
    System.out.println("  " + availableLanguages.get(i).getString());
247
}
248

249
api.End();
250
```
251

252
### Callback Function Types
253

254
Function pointer interfaces for progress monitoring and cancellation.
255

256
```java { .api }
257
/**
258
 * Callback for cancelling OCR operations
259
 * Return true to cancel processing
260
 */
261
public abstract class TessCancelFunc extends FunctionPointer {
262
    public abstract boolean call(Pointer cancel_this, int words);
263
}
264

265
/**
266
 * Progress monitoring callback  
267
 * Called periodically during OCR processing
268
 */
269
public abstract class TessProgressFunc extends FunctionPointer {
270
    public abstract boolean call(ETEXT_DESC ths, int left, int right, int top, int bottom);
271
}
272

273
/**
274
 * Dictionary validation function
275
 * Used for custom dictionary checking
276
 */
277
public abstract class DictFunc extends FunctionPointer {
278
    public abstract int call(Dict o, Pointer arg0, UNICHARSET arg1, int arg2, boolean arg3);
279
}
280

281
/**
282
 * Context-based probability calculation
283
 * Used in advanced recognition scenarios
284
 */
285
public abstract class ProbabilityInContextFunc extends FunctionPointer {
286
    public abstract double call(Dict o, String arg0, String arg1, int arg2, String arg3, int arg4);
287
}
288

289
/**
290
 * File reading callback for custom input sources
291
 * Allows custom file handling implementations
292
 */
293
public abstract class FileReader extends FunctionPointer {
294
    public abstract boolean call(String filename, ByteVector data);
295
}
296

297
// Legacy callback types for compatibility
298
public abstract class CANCEL_FUNC extends FunctionPointer { }
299
public abstract class PROGRESS_FUNC extends FunctionPointer { }
300
public abstract class PROGRESS_FUNC2 extends FunctionPointer { }
301
```
302

303
**Custom Progress Callback Example:**
304

305
```java
306
// Create custom progress callback
307
TessProgressFunc progressCallback = new TessProgressFunc() {
308
    @Override
309
    public boolean call(ETEXT_DESC desc, int left, int right, int top, int bottom) {
310
        int progress = desc.progress();
311
        System.out.println("OCR Progress: " + progress + "% - Processing region (" + 
312
                          left + "," + top + ") to (" + right + "," + bottom + ")");
313
        
314
        // Return false to continue, true to cancel
315
        return progress > 50; // Cancel after 50% for demo
316
    }
317
};
318

319
// Create cancellation callback
320
TessCancelFunc cancelCallback = new TessCancelFunc() {
321
    @Override
322
    public boolean call(Pointer cancel_this, int words) {
323
        System.out.println("Processed " + words + " words so far");
324
        // Return true to cancel processing
325
        return false; // Don't cancel
326
    }
327
};
328

329
// Use callbacks with monitor
330
ETEXT_DESC monitor = TessMonitorCreate();
331
// Note: Setting callbacks requires additional native integration
332
```
333

334
### Internal and Opaque Classes
335

336
Classes representing internal Tesseract structures with limited exposed functionality.
337

338
```java { .api }
339
// Core engine classes (opaque - limited functionality)
340
public class Tesseract extends Pointer { }              // Core Tesseract engine
341
public class ImageThresholder extends Pointer { }       // Image processing
342
public class OSResults extends Pointer { }              // Orientation/script detection results
343

344
// Dictionary and language model classes  
345
public class Dict extends Pointer { }                   // Dictionary management
346
public class Dawg extends Pointer { }                   // Directed Acyclic Word Graph
347
public class UNICHARSET extends Pointer { }             // Character set management
348

349
// Analysis and detection classes
350
public class EquationDetect extends Pointer { }         // Equation detection
351
public class ParagraphModel extends Pointer { }         // Paragraph modeling
352
public class BlamerBundle extends Pointer { }           // Training/debugging information
353

354
// Internal result structures
355
public class PAGE_RES extends Pointer { }               // Page results
356
public class PAGE_RES_IT extends Pointer { }            // Page results iterator
357
public class WERD extends Pointer { }                   // Word structure
358
public class WERD_RES extends Pointer { }               // Word results
359
public class BLOB_CHOICE_IT extends Pointer { }         // Blob choice iterator
360
public class C_BLOB_IT extends Pointer { }              // C blob iterator
361
public class BLOCK_LIST extends Pointer { }             // Block list structure
362
```
363

364
### Constants and Enumerations
365

366
Important constants used throughout the API.
367

368
```java { .api }
369
// Version Constants
370
public static final int TESSERACT_MAJOR_VERSION = 5;
371
public static final int TESSERACT_MINOR_VERSION = 5;
372
public static final int TESSERACT_MICRO_VERSION = 1;
373
public static final String TESSERACT_VERSION_STR = "5.5.1";
374

375
// Unicode Constants
376
public static final int UNICHAR_LEN = 30;              // Maximum UNICHAR length
377
public static final int INVALID_UNICHAR_ID = -1;       // Invalid character ID
378

379
// Script Direction Constants
380
public static final int DIR_NEUTRAL = 0;               // Neutral direction
381
public static final int DIR_LEFT_TO_RIGHT = 1;         // Left-to-right text
382
public static final int DIR_RIGHT_TO_LEFT = 2;         // Right-to-left text
383
public static final int DIR_MIX = 3;                   // Mixed directions
384

385
// Orientation Constants
386
public static final int ORIENTATION_PAGE_UP = 0;       // Page upright
387
public static final int ORIENTATION_PAGE_RIGHT = 1;    // Page rotated right
388
public static final int ORIENTATION_PAGE_DOWN = 2;     // Page upside down
389
public static final int ORIENTATION_PAGE_LEFT = 3;     // Page rotated left
390

391
// Writing Direction Constants
392
public static final int WRITING_DIRECTION_LEFT_TO_RIGHT = 0;
393
public static final int WRITING_DIRECTION_RIGHT_TO_LEFT = 1;
394
public static final int WRITING_DIRECTION_TOP_TO_BOTTOM = 2;
395

396
// Text Line Order Constants  
397
public static final int TEXTLINE_ORDER_LEFT_TO_RIGHT = 0;
398
public static final int TEXTLINE_ORDER_RIGHT_TO_LEFT = 1;
399
public static final int TEXTLINE_ORDER_TOP_TO_BOTTOM = 2;
400

401
// Paragraph Justification Constants
402
public static final int JUSTIFICATION_UNKNOWN = 0;
403
public static final int JUSTIFICATION_LEFT = 1;
404
public static final int JUSTIFICATION_CENTER = 2;
405
public static final int JUSTIFICATION_RIGHT = 3;
406
```
407

408
### PolyBlock Type Constants
409

410
Constants for identifying different types of page regions.
411

412
```java { .api }
413
// PolyBlock Type Constants for page layout analysis
414
public static final int PT_UNKNOWN = 0;             // Unknown region type
415
public static final int PT_FLOWING_TEXT = 1;        // Flowing text within column
416
public static final int PT_HEADING_TEXT = 2;        // Heading text spanning columns
417
public static final int PT_PULLOUT_TEXT = 3;        // Pull-out text region
418
public static final int PT_EQUATION = 4;            // Mathematical equation
419
public static final int PT_INLINE_EQUATION = 5;     // Inline equation
420
public static final int PT_TABLE = 6;               // Table region
421
public static final int PT_VERTICAL_TEXT = 7;       // Vertical text line
422
public static final int PT_CAPTION_TEXT = 8;        // Image caption text
423
public static final int PT_FLOWING_IMAGE = 9;       // Image within column
424
public static final int PT_HEADING_IMAGE = 10;      // Image spanning columns
425
public static final int PT_PULLOUT_IMAGE = 11;      // Pull-out image region
426
public static final int PT_HORZ_LINE = 12;          // Horizontal line
427
public static final int PT_VERT_LINE = 13;          // Vertical line
428
public static final int PT_NOISE = 14;              // Noise outside columns
429
```
430

431
## Memory Management Guidelines
432

433
**Important Data Structure Guidelines:**
434
- Always call `deallocate()` on BytePointer objects returned by text methods
435
- Use `TessMonitorCreate()` and `TessMonitorDelete()` for progress monitors
436
- StringVector and other containers are automatically managed by JavaCPP
437
- UNICHAR `utf8_str()` method requires manual `deallocate()` call
438
- Callback functions are automatically managed through JavaCPP
439
- Check for null pointers before accessing data structure members
440

441
**Performance Considerations:**
442
- Reuse containers when possible to reduce memory allocation
443
- Clear large containers when done to free memory promptly
444
- Use appropriate container sizes to avoid frequent reallocations
445
- Monitor memory usage when processing large batches of documents