0
# High-Level Functions
1

2
High-level functions provide convenient one-shot OCR operations without requiring manual worker management. They automatically create workers, perform the requested operation, and clean up resources, making them ideal for simple use cases or prototyping.
3

4
## Capabilities
5

6
### Text Recognition
7

8
Performs text recognition on an image with automatic worker lifecycle management.
9

10
```javascript { .api }
11
/**
12
 * Recognizes text from an image using automatic worker management
13
 * @param image - Image input in various supported formats
14
 * @param langs - Language code(s) for recognition (default: 'eng')
15
 * @param options - Worker configuration options
16
 * @returns Promise resolving to recognition results
17
 */
18
function recognize(
19
  image: ImageLike, 
20
  langs?: string, 
21
  options?: Partial<WorkerOptions>
22
): Promise<RecognizeResult>;
23
```
24

25
**Usage Examples:**
26

27
```javascript
28
import { recognize } from 'tesseract.js';
29

30
// Basic recognition with English
31
const result = await recognize('https://example.com/image.png');
32
console.log(result.data.text);
33

34
// Recognition with specific language
35
const frenchResult = await recognize('french-document.jpg', 'fra');
36
console.log(frenchResult.data.text);
37

38
// Recognition with multiple languages
39
const multiResult = await recognize('mixed-text.png', 'eng+fra+deu');
40
console.log(multiResult.data.text);
41

42
// Recognition with custom options
43
const customResult = await recognize('image.png', 'eng', {
44
  logger: m => console.log(`Progress: ${m.progress}%`)
45
});
46
```
47

48
### Orientation and Script Detection
49

50
Detects text orientation and script information from an image with automatic worker management.
51

52
```javascript { .api }
53
/**
54
 * Detects orientation and script from an image using automatic worker management
55
 * @param image - Image input in various supported formats
56
 * @param options - Worker configuration options
57
 * @returns Promise resolving to detection results
58
 */
59
function detect(
60
  image: ImageLike, 
61
  options?: Partial<WorkerOptions>
62
): Promise<DetectResult>;
63
```
64

65
**Usage Examples:**
66

67
```javascript
68
import { detect } from 'tesseract.js';
69

70
// Basic detection
71
const detection = await detect('rotated-image.png');
72
console.log(`Orientation: ${detection.data.orientation_degrees}°`);
73
console.log(`Script: ${detection.data.script}`);
74
console.log(`Script confidence: ${detection.data.script_confidence}`);
75

76
// Detection with custom options
77
const customDetection = await detect('image.png', {
78
  logger: m => console.log(`Detection progress: ${m.progress}%`)
79
});
80
```
81

82
## Comparison with Worker API
83

84
### When to Use High-Level Functions
85

86
**Best for:**
87
- Quick prototyping and testing
88
- Single image processing
89
- Simple scripts and demos
90
- Cases where performance is not critical
91
- One-off OCR operations
92

93
**Example scenarios:**
94
```javascript
95
// Quick text extraction from a single image
96
const text = (await recognize('receipt.jpg')).data.text;
97

98
// Check if an image contains rotated text
99
const isRotated = (await detect('document.png')).data.orientation_degrees !== 0;
100
```
101

102
### When to Use Worker API
103

104
**Best for:**
105
- Processing multiple images
106
- Applications requiring configuration changes
107
- Performance-critical applications
108
- Advanced parameter tuning
109
- Resource-intensive operations
110

111
**Example scenarios:**
112
```javascript
113
// Process many images efficiently
114
const worker = await createWorker('eng');
115
for (const image of images) {
116
  const result = await worker.recognize(image);
117
  // Process result
118
}
119
await worker.terminate();
120
```
121

122
## Complete Usage Examples
123

124
### Document Processing Pipeline
125

126
```javascript
127
import { recognize, detect } from 'tesseract.js';
128

129
async function processDocument(imagePath) {
130
  try {
131
    // First detect orientation
132
    const detection = await detect(imagePath);
133
    
134
    if (detection.data.orientation_degrees !== 0) {
135
      console.log(`Image is rotated ${detection.data.orientation_degrees}°`);
136
    }
137
    
138
    // Then recognize text
139
    const result = await recognize(imagePath, 'eng');
140
    
141
    return {
142
      text: result.data.text,
143
      confidence: result.data.confidence,
144
      orientation: detection.data.orientation_degrees,
145
      script: detection.data.script
146
    };
147
  } catch (error) {
148
    console.error('Processing failed:', error);
149
    throw error;
150
  }
151
}
152

153
// Usage
154
const document = await processDocument('scanned-page.jpg');
155
console.log(document.text);
156
```
157

158
### Multi-Language Document Analysis
159

160
```javascript
161
import { recognize, detect, languages } from 'tesseract.js';
162

163
async function analyzeMultilingualDocument(imagePath) {
164
  // Detect script first
165
  const detection = await detect(imagePath);
166
  console.log(`Detected script: ${detection.data.script}`);
167
  
168
  // Choose appropriate languages based on script
169
  let langs = 'eng'; // default
170
  if (detection.data.script === 'Latin') {
171
    langs = 'eng+fra+deu+spa'; // Common Latin script languages
172
  } else if (detection.data.script === 'Han') {
173
    langs = 'chi_sim+chi_tra'; // Chinese variants
174
  }
175
  
176
  // Recognize with appropriate languages
177
  const result = await recognize(imagePath, langs);
178
  
179
  return {
180
    detectedScript: detection.data.script,
181
    usedLanguages: langs,
182
    text: result.data.text,
183
    confidence: result.data.confidence
184
  };
185
}
186

187
// Usage
188
const analysis = await analyzeMultilingualDocument('multilingual-doc.png');
189
console.log(`Script: ${analysis.detectedScript}`);
190
console.log(`Languages used: ${analysis.usedLanguages}`);
191
console.log(`Text: ${analysis.text}`);
192
```
193

194
### Batch Processing with High-Level Functions
195

196
```javascript
197
import { recognize } from 'tesseract.js';
198

199
async function processBatch(imagePaths, concurrency = 3) {
200
  const results = [];
201
  
202
  // Process in chunks to avoid overwhelming the system
203
  for (let i = 0; i < imagePaths.length; i += concurrency) {
204
    const chunk = imagePaths.slice(i, i + concurrency);
205
    
206
    console.log(`Processing chunk ${Math.floor(i/concurrency) + 1}/${Math.ceil(imagePaths.length/concurrency)}`);
207
    
208
    const chunkResults = await Promise.all(
209
      chunk.map(async (imagePath, index) => {
210
        try {
211
          const result = await recognize(imagePath, 'eng', {
212
            logger: m => console.log(`Image ${i + index + 1}: ${m.status} - ${m.progress}%`)
213
          });
214
          return { imagePath, text: result.data.text, success: true };
215
        } catch (error) {
216
          console.error(`Failed to process ${imagePath}:`, error);
217
          return { imagePath, error: error.message, success: false };
218
        }
219
      })
220
    );
221
    
222
    results.push(...chunkResults);
223
  }
224
  
225
  return results;
226
}
227

228
// Usage
229
const imagePaths = ['doc1.jpg', 'doc2.png', 'doc3.pdf', 'doc4.jpg'];
230
const results = await processBatch(imagePaths);
231

232
const successful = results.filter(r => r.success);
233
const failed = results.filter(r => !r.success);
234

235
console.log(`Successfully processed: ${successful.length}`);
236
console.log(`Failed: ${failed.length}`);
237
```
238

239
### Error Handling Best Practices
240

241
```javascript
242
import { recognize, detect } from 'tesseract.js';
243

244
async function robustOCR(imagePath, retries = 2) {
245
  for (let attempt = 1; attempt <= retries + 1; attempt++) {
246
    try {
247
      console.log(`Attempt ${attempt} for ${imagePath}`);
248
      
249
      const result = await recognize(imagePath, 'eng', {
250
        logger: m => {
251
          if (m.status === 'recognizing text') {
252
            console.log(`Progress: ${m.progress}%`);
253
          }
254
        },
255
        errorHandler: (error) => {
256
          console.warn(`Worker warning:`, error);
257
        }
258
      });
259
      
260
      if (result.data.confidence < 50) {
261
        console.warn(`Low confidence (${result.data.confidence}%) for ${imagePath}`);
262
      }
263
      
264
      return result;
265
      
266
    } catch (error) {
267
      console.error(`Attempt ${attempt} failed:`, error.message);
268
      
269
      if (attempt === retries + 1) {
270
        throw new Error(`OCR failed after ${retries + 1} attempts: ${error.message}`);
271
      }
272
      
273
      // Wait before retry
274
      await new Promise(resolve => setTimeout(resolve, 1000 * attempt));
275
    }
276
  }
277
}
278

279
// Usage with error handling
280
try {
281
  const result = await robustOCR('difficult-image.jpg');
282
  console.log('OCR successful:', result.data.text);
283
} catch (error) {
284
  console.error('OCR ultimately failed:', error.message);
285
}
286
```
287

288
## Result Types
289

290
The high-level functions return the same result types as the Worker API:
291

292
```javascript { .api }
293
interface RecognizeResult {
294
  jobId: string;
295
  data: Page;
296
}
297

298
interface DetectResult {
299
  jobId: string;
300
  data: DetectData;
301
}
302

303
interface DetectData {
304
  tesseract_script_id: number | null;
305
  script: string | null;
306
  script_confidence: number | null;
307
  orientation_degrees: number | null;
308
  orientation_confidence: number | null;
309
}
310
```