0
# Configuration
1

2
Comprehensive configuration system with hundreds of parameters controlling OCR behavior, page segmentation, character recognition, and output formatting. Tesseract provides fine-grained control over recognition algorithms and processing options.
3

4
## Capabilities
5

6
### Parameter Management
7

8
Set and retrieve configuration parameters that control Tesseract's behavior during initialization and recognition.
9

10
```java { .api }
11
public class TessBaseAPI {
12
    // Parameter setting
13
    public boolean SetVariable(String name, String value);
14
    public boolean SetDebugVariable(String name, String value);
15
    
16
    // Parameter retrieval
17
    public boolean GetIntVariable(String name, int[] value);
18
    public boolean GetBoolVariable(String name, boolean[] value);
19
    public boolean GetDoubleVariable(String name, double[] value);
20
    public String GetStringVariable(String name);
21
    
22
    // Generic parameter access
23
    public native @Cast("bool") boolean GetVariableAsString(String name, @StdString @Cast({"char*", "std::string*"}) BytePointer val);
24
    
25
    // Parameter introspection
26
    public void PrintVariables(Pointer fp);
27
}
28
```
29

30
**Parameter Types:**
31
- **String Parameters**: Language codes, file paths, character sets
32
- **Integer Parameters**: Thresholds, limits, numeric options
33
- **Boolean Parameters**: Feature toggles, mode switches
34
- **Double Parameters**: Floating-point thresholds, scaling factors
35

36
#### Usage Example
37

38
```java
39
TessBaseAPI api = new TessBaseAPI();
40
api.Init(null, "eng");
41

42
// Set character blacklist (ignore these characters)
43
api.SetVariable("tessedit_char_blacklist", "xyz@#$");
44

45
// Enable numeric-only mode
46
api.SetVariable("classify_bln_numeric_mode", "1");
47

48
// Set minimum word length
49
api.SetVariable("textord_min_linesize", "2.5");
50

51
// Enable debug output
52
api.SetDebugVariable("textord_debug_tabfind", "1");
53

54
// Check if parameter exists and get value
55
int[] min_chars = new int[1];
56
if (api.GetIntVariable("textord_min_chars_in_word", min_chars)) {
57
    System.out.println("Minimum characters per word: " + min_chars[0]);
58
}
59

60
// Get string parameter
61
String lang = api.GetStringVariable("tessedit_init_config_only");
62
System.out.println("Config only mode: " + lang);
63
```
64

65
### OCR Engine Mode Configuration
66

67
Control which OCR engine and neural network models are used for recognition.
68

69
```java { .api }
70
// OCR Engine Mode constants
71
public static final int OEM_TESSERACT_ONLY = 0;           // Legacy Tesseract (deprecated)
72
public static final int OEM_LSTM_ONLY = 1;                // LSTM neural network only  
73
public static final int OEM_TESSERACT_LSTM_COMBINED = 2;  // Combined legacy + LSTM (deprecated)
74
public static final int OEM_DEFAULT = 3;                  // Default (currently LSTM only)
75
```
76

77
#### Usage Example
78

79
```java
80
TessBaseAPI api = new TessBaseAPI();
81

82
// Use LSTM-only engine (recommended)
83
int result = api.Init(null, "eng", OEM_LSTM_ONLY);
84

85
// Or use default engine mode
86
int result2 = api.Init(null, "eng", OEM_DEFAULT);
87

88
// Check which engine is active
89
String engine_mode = api.GetStringVariable("tessedit_ocr_engine_mode");
90
System.out.println("Active OCR engine: " + engine_mode);
91
```
92

93
### Page Segmentation Configuration
94

95
Configure how Tesseract analyzes page layout and identifies text regions.
96

97
```java { .api }
98
public class TessBaseAPI {
99
    // Page segmentation mode control
100
    public void SetPageSegMode(int mode);
101
    public int GetPageSegMode();
102
}
103

104
// Page segmentation mode constants (detailed)
105
public static final int PSM_OSD_ONLY = 0;              // Orientation/script detection only
106
public static final int PSM_AUTO_OSD = 1;              // Automatic with OSD
107
public static final int PSM_AUTO_ONLY = 2;             // Automatic without OSD
108
public static final int PSM_AUTO = 3;                  // Fully automatic (default)
109
public static final int PSM_SINGLE_COLUMN = 4;         // Single column text
110
public static final int PSM_SINGLE_BLOCK_VERT_TEXT = 5; // Single vertical block
111
public static final int PSM_SINGLE_BLOCK = 6;          // Single uniform block
112
public static final int PSM_SINGLE_LINE = 7;           // Single text line
113
public static final int PSM_SINGLE_WORD = 8;           // Single word
114
public static final int PSM_CIRCLE_WORD = 9;           // Single word in circle
115
public static final int PSM_SINGLE_CHAR = 10;          // Single character
116
public static final int PSM_SPARSE_TEXT = 11;          // Sparse text find
117
public static final int PSM_SPARSE_TEXT_OSD = 12;      // Sparse text with OSD
118
public static final int PSM_RAW_LINE = 13;             // Raw line (bypass hacks)
119
```
120

121
#### Usage Example
122

123
```java
124
TessBaseAPI api = new TessBaseAPI();
125
api.Init(null, "eng");
126

127
// Configure for different document types
128
switch (documentType) {
129
    case NEWSPAPER:
130
        api.SetPageSegMode(PSM_AUTO);  // Multi-column with auto detection
131
        break;
132
        
133
    case BUSINESS_CARD:
134
        api.SetPageSegMode(PSM_SINGLE_BLOCK);  // Simple layout
135
        break;
136
        
137
    case LICENSE_PLATE:
138
        api.SetPageSegMode(PSM_SINGLE_LINE);   // Single line of text
139
        break;
140
        
141
    case CAPTCHA:
142
        api.SetPageSegMode(PSM_SINGLE_WORD);   // Single word
143
        break;
144
        
145
    case RECEIPT:
146
        api.SetPageSegMode(PSM_SINGLE_COLUMN); // Vertical list
147
        break;
148
}
149

150
// Verify current mode
151
int currentMode = api.GetPageSegMode();
152
System.out.println("Page segmentation mode: " + currentMode);
153
```
154

155
### Character Recognition Configuration
156

157
Fine-tune character recognition algorithms and thresholds.
158

159
#### Common Character Recognition Parameters
160

161
```java
162
// Character filtering and validation
163
api.SetVariable("tessedit_char_whitelist", "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz ");
164
api.SetVariable("tessedit_char_blacklist", "!@#$%^&*()");
165

166
// Numeric mode for numbers-only recognition
167
api.SetVariable("classify_bln_numeric_mode", "1");
168

169
// Case sensitivity
170
api.SetVariable("unicharset_use_script_ider", "1");
171

172
// Character segmentation
173
api.SetVariable("chop_enable", "1");              // Enable character chopping
174
api.SetVariable("use_new_state_cost", "1");       // Use improved state cost
175
api.SetVariable("segment_segcost_rating", "1");   // Enable segmentation cost rating
176

177
// Word recognition
178
api.SetVariable("save_best_choices", "1");        // Save alternative choices
179
api.SetVariable("language_model_penalty_non_dict_word", "0.15");
180
api.SetVariable("language_model_penalty_non_freq_dict_word", "0.1");
181
```
182

183
#### Usage Example
184

185
```java
186
TessBaseAPI api = new TessBaseAPI();
187
api.Init(null, "eng");
188

189
// Configure for license plate recognition
190
api.SetPageSegMode(PSM_SINGLE_LINE);
191
api.SetVariable("tessedit_char_whitelist", "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789");
192
api.SetVariable("classify_bln_numeric_mode", "0");  // Allow letters
193
api.SetVariable("textord_min_chars_in_word", "3");
194

195
// Configure for invoice numbers
196
api.SetPageSegMode(PSM_SINGLE_WORD);
197
api.SetVariable("tessedit_char_whitelist", "0123456789-");
198
api.SetVariable("classify_bln_numeric_mode", "1");
199

200
// Configure for general document with high accuracy
201
api.SetPageSegMode(PSM_AUTO);
202
api.SetVariable("tessedit_pageseg_mode", "3");
203
api.SetVariable("classify_enable_learning", "1");
204
api.SetVariable("classify_enable_adaptive_matcher", "1");
205
```
206

207
### Image Processing Configuration
208

209
Control image preprocessing and enhancement algorithms.
210

211
#### Image Processing Parameters
212

213
```java
214
// Image enhancement
215
api.SetVariable("textord_heavy_nr", "1");           // Enable heavy noise reduction
216
api.SetVariable("textord_noise_rejrows", "1");      // Reject noisy rows
217
api.SetVariable("textord_noise_rejwords", "1");     // Reject noisy words
218

219
// Skew detection and correction
220
api.SetVariable("textord_straight_baselines", "0"); // Allow curved baselines
221
api.SetVariable("textord_old_baselines", "1");      // Use old baseline fitting
222
api.SetVariable("textord_debug_baselines", "0");    // Debug baseline detection
223

224
// Text line finding
225
api.SetVariable("textord_really_old_xheight", "0"); // Use new x-height algorithm
226
api.SetVariable("textord_fix_xheight_bug", "1");    // Fix x-height bugs
227
api.SetVariable("textord_fix_makerow_bug", "1");    // Fix row-making bugs
228

229
// Edge detection
230
api.SetVariable("edges_use_new_outline_complexity", "1");
231
api.SetVariable("edges_max_children_per_outline", "10");
232
```
233

234
#### Usage Example
235

236
```java
237
TessBaseAPI api = new TessBaseAPI();
238
api.Init(null, "eng");
239

240
// Configure for poor quality scanned documents
241
api.SetVariable("textord_heavy_nr", "1");
242
api.SetVariable("textord_noise_rejrows", "1");
243
api.SetVariable("textord_noise_rejwords", "1");
244
api.SetVariable("edges_use_new_outline_complexity", "1");
245

246
// Configure for high-quality printed text
247
api.SetVariable("textord_really_old_xheight", "0");
248
api.SetVariable("textord_fix_xheight_bug", "1");
249
api.SetVariable("classify_enable_adaptive_matcher", "1");
250

251
// Configure for handwritten text
252
api.SetVariable("classify_enable_learning", "1");
253
api.SetVariable("classify_adapt_proto_threshold", "230");
254
api.SetVariable("classify_adapt_feature_threshold", "230");
255
```
256

257
### Debug and Logging Configuration
258

259
Enable detailed logging and debug output for troubleshooting and analysis.
260

261
#### Debug Parameters
262

263
```java
264
// General debug output
265
api.SetDebugVariable("classify_debug_level", "2");
266
api.SetDebugVariable("textord_debug_tabfind", "1");
267
api.SetDebugVariable("textord_show_initial_words", "1");
268

269
// Image processing debug
270
api.SetDebugVariable("textord_debug_images", "1");
271
api.SetDebugVariable("textord_debug_to_screen", "1");
272

273
// Classification debug
274
api.SetDebugVariable("matcher_debug_level", "2");
275
api.SetDebugVariable("stopper_debug_level", "1");
276

277
// Layout analysis debug
278
api.SetDebugVariable("equationdetect_save_bi_image", "1");
279
api.SetDebugVariable("paragraph_debug_level", "1");
280
```
281

282
#### Usage Example
283

284
```java
285
TessBaseAPI api = new TessBaseAPI();
286
api.Init(null, "eng");
287

288
// Enable comprehensive debugging for development
289
if (debugMode) {
290
    api.SetDebugVariable("classify_debug_level", "3");
291
    api.SetDebugVariable("textord_debug_tabfind", "1");
292
    api.SetDebugVariable("textord_debug_images", "1");
293
    api.SetDebugVariable("matcher_debug_level", "2");
294
    
295
    // Set debug output directory
296
    api.SetOutputName("/tmp/tesseract_debug");
297
}
298

299
// Enable specific debugging for problem analysis
300
if (layoutProblems) {
301
    api.SetDebugVariable("textord_show_initial_words", "1");
302
    api.SetDebugVariable("paragraph_debug_level", "2");
303
}
304

305
if (characterRecognitionProblems) {
306
    api.SetDebugVariable("classify_debug_level", "2");
307
    api.SetDebugVariable("stopper_debug_level", "1");
308
}
309
```
310

311
### Performance and Resource Configuration
312

313
Control memory usage, processing speed, and computational resources.
314

315
#### Performance Parameters
316

317
```java
318
// Processing timeouts
319
api.SetVariable("tessedit_timeout_millisecs", "30000");  // 30 second timeout
320

321
// Memory management
322
api.SetVariable("max_permuter_attempts", "10000");       // Limit word permutations
323
api.SetVariable("stopper_smallword_size", "2");          // Small word threshold
324

325
// Processing limits
326
api.SetVariable("language_model_penalty_increment", "0.01");
327
api.SetVariable("segment_penalty_dict_nonword", "1.25");
328
api.SetVariable("segment_penalty_garbage", "1.50");
329

330
// Quality vs speed trade-offs
331
api.SetVariable("tessedit_resegment_from_boxes", "1");   // Re-segment from boxes
332
api.SetVariable("tessedit_resegment_from_line_boxes", "1");
333
api.SetVariable("tessedit_train_from_boxes", "0");       // Disable training mode
334
```
335

336
#### Usage Example
337

338
```java
339
TessBaseAPI api = new TessBaseAPI();
340
api.Init(null, "eng");
341

342
// Configure for high-speed processing
343
api.SetVariable("tessedit_timeout_millisecs", "5000");   // 5 second limit
344
api.SetVariable("max_permuter_attempts", "5000");        // Reduce attempts
345
api.SetVariable("stopper_smallword_size", "3");          // Larger small word threshold
346

347
// Configure for high-accuracy processing
348
api.SetVariable("tessedit_timeout_millisecs", "60000");  // 60 second limit
349
api.SetVariable("max_permuter_attempts", "20000");       // More attempts
350
api.SetVariable("classify_enable_adaptive_matcher", "1");
351
api.SetVariable("classify_enable_learning", "1");
352

353
// Configure for batch processing
354
api.SetVariable("tessedit_do_invert", "1");              // Auto-invert if needed
355
api.SetVariable("tessedit_write_images", "0");           // Don't save debug images
356
api.SetVariable("tessedit_dump_pageseg_images", "0");    // Don't save segmentation images
357
```
358

359
### Configuration File Support
360

361
Load configuration from files and manage configuration sets.
362

363
```java { .api }
364
// Configuration file parameters
365
api.SetVariable("tessedit_init_config_only", "0");       // Load config files
366
api.SetVariable("user_defined_dpi", "300");              // Set DPI if not detected
367
```
368

369
#### Usage Example
370

371
```java
372
// Create configuration files for different use cases
373

374
// config_highaccuracy.txt
375
"""
376
classify_enable_adaptive_matcher 1
377
classify_enable_learning 1
378
tessedit_timeout_millisecs 60000
379
textord_heavy_nr 1
380
max_permuter_attempts 20000
381
"""
382

383
// config_speed.txt  
384
"""
385
tessedit_timeout_millisecs 5000
386
max_permuter_attempts 5000
387
classify_enable_adaptive_matcher 0
388
classify_enable_learning 0
389
"""
390

391
// Use configuration files
392
TessBaseAPI api = new TessBaseAPI();
393
// Configuration files are loaded automatically from tessdata/configs/
394
// when specified in Init
395
api.Init("/usr/share/tessdata", "eng+config_highaccuracy");
396
```
397

398
## Common Configuration Patterns
399

400
### Document Type Specific Configurations
401

402
```java
403
public class TesseractConfigurations {
404
    
405
    public static void configureForNewspaper(TessBaseAPI api) {
406
        api.SetPageSegMode(PSM_AUTO);
407
        api.SetVariable("textord_tabfind_find_tables", "1");
408
        api.SetVariable("textord_tablefind_good_width", "3");
409
    }
410
    
411
    public static void configureForBusinessCard(TessBaseAPI api) {
412
        api.SetPageSegMode(PSM_SINGLE_BLOCK);
413
        api.SetVariable("preserve_interword_spaces", "1");
414
        api.SetVariable("tessedit_char_whitelist", 
415
                       "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789@.-+() ");
416
    }
417
    
418
    public static void configureForInvoice(TessBaseAPI api) {
419
        api.SetPageSegMode(PSM_AUTO);
420
        api.SetVariable("preserve_interword_spaces", "1");
421
        api.SetVariable("textord_tabfind_find_tables", "1");
422
    }
423
    
424
    public static void configureForLicensePlate(TessBaseAPI api) {
425
        api.SetPageSegMode(PSM_SINGLE_LINE);
426
        api.SetVariable("tessedit_char_whitelist", "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789");
427
        api.SetVariable("classify_bln_numeric_mode", "0");
428
        api.SetVariable("textord_min_chars_in_word", "1");
429
    }
430
}
431
```
432

433
## Types
434

435
### Configuration Parameter Types
436

437
```java { .api }
438
// Parameter value types
439
public class TessBaseAPI {
440
    // Integer parameters (thresholds, counts, modes)
441
    public boolean GetIntVariable(String name, int[] value);
442
    
443
    // Boolean parameters (feature toggles)
444
    public boolean GetBoolVariable(String name, boolean[] value);
445
    
446
    // Double parameters (floating-point thresholds)
447
    public boolean GetDoubleVariable(String name, double[] value);
448
    
449
    // String parameters (paths, character sets, languages)
450
    public String GetStringVariable(String name);
451
}
452
```
453

454
### Engine Mode Constants
455

456
```java { .api }
457
public static final int OEM_TESSERACT_ONLY = 0;           // Legacy engine
458
public static final int OEM_LSTM_ONLY = 1;                // LSTM neural network
459
public static final int OEM_TESSERACT_LSTM_COMBINED = 2;  // Combined (deprecated)
460
public static final int OEM_DEFAULT = 3;                  // Default mode
461
```
462

463
### Page Segmentation Constants
464

465
```java { .api }
466
public static final int PSM_OSD_ONLY = 0;
467
public static final int PSM_AUTO_OSD = 1;
468
public static final int PSM_AUTO_ONLY = 2;   
469
public static final int PSM_AUTO = 3;
470
public static final int PSM_SINGLE_COLUMN = 4;
471
public static final int PSM_SINGLE_BLOCK_VERT_TEXT = 5;
472
public static final int PSM_SINGLE_BLOCK = 6;
473
public static final int PSM_SINGLE_LINE = 7;
474
public static final int PSM_SINGLE_WORD = 8;
475
public static final int PSM_CIRCLE_WORD = 9;
476
public static final int PSM_SINGLE_CHAR = 10;
477
public static final int PSM_SPARSE_TEXT = 11;
478
public static final int PSM_SPARSE_TEXT_OSD = 12;
479
public static final int PSM_RAW_LINE = 13;
480
```