Tesseract OCR Engine Administrator & Developer Guide

1. Architecture Overview

Tesseract is a mature open-source OCR engine originally developed at Hewlett-Packard (1985-1995) and subsequently sponsored by Google (2006-2018). It processes raster images through a multi-stage pipeline: image loading via Leptonica, page layout analysis (text block/line/word detection), character segmentation, and recognition using either an LSTM neural network (primary) or the legacy pattern-based classifier (deprecated but available). The engine supports 100+ languages via downloadable trained data files and produces output in multiple formats.

The codebase is C++17 with a C compatibility layer, organized into a shared library (libtesseract) and a CLI executable that links against it. Training utilities are separate executables that share common training libraries.

Component Architecture

Input Image
    │
    ▼
┌─────────────────────────────────────────────────┐
│                  Leptonica                       │
│         (Image I/O, format conversion)           │
└──────────────────────┬──────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────┐
│              ImageThresholder                     │
│    (Otsu binarization → src/ccstruct/otsuthr)    │
└──────────────────────┬──────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────┐
│             Page Layout Analysis                 │
│  ┌─────────────┐  ┌──────────────┐              │
│  │ textord/     │  │ ccmain/      │              │
│  │ Column finder│  │ Page seg     │              │
│  │ Line finder  │  │ Paragraph    │              │
│  │ Word seg     │  │ detection    │              │
│  └─────────────┘  └──────────────┘              │
└──────────────────────┬──────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────┐
│              Recognition Engine                  │
│  ┌─────────────────┐  ┌───────────────────┐     │
│  │ LSTM Engine      │  │ Legacy Engine      │     │
│  │ (src/lstm/)      │  │ (src/classify/)    │     │
│  │ Neural network   │  │ Pattern matching   │     │
│  │ Primary engine   │  │ Adaptive training  │     │
│  └─────────────────┘  └───────────────────┘     │
└──────────────────────┬──────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────┐
│              Output Renderers                    │
│  (src/api/)                                      │
│  Text │ hOCR │ ALTO │ PAGE │ TSV │ PDF │ Box    │
└─────────────────────────────────────────────────┘

Note

The legacy engine is compiled out when DISABLED_LEGACY_ENGINE is defined. LSTM-only builds skip the legacy classifier, adaptive training, and OSD modes, resulting in a smaller binary.

Component Inventory

Technology Stack

2. System Requirements

Build Requirements

Build Dependencies (Debian/Ubuntu)

sudo apt install -y \
  cmake g++ make pkg-config \
  libleptonica-dev \
  libpng-dev libjpeg-dev libtiff-dev zlib1g-dev \
  libicu-dev libpango1.0-dev libcairo2-dev \
  libarchive-dev libcurl4-openssl-dev

Runtime Requirements

SIMD Support Matrix

Tesseract detects CPU SIMD capabilities at runtime and dispatches optimized dot product and integer SIMD matrix functions:

Tip

Check detected SIMD with tesseract --version. If only "Found SSE4.1" appears on a CPU that supports AVX2, verify that the binary was compiled without -mno-avx2 or equivalent.

3. Configuration Reference

Config File System

Tesseract's configuration is entirely parameter-based. Parameters are typed (INT_VAR, BOOL_VAR, DOUBLE_VAR, STRING_VAR) and can be set via:

1. Config files in tessdata/configs/ or tessdata/tessconfigs/ (read during Init())
2. -c VAR=VALUE on the command line
3. SetVariable() in the C++/C API (after Init(), non-init params only)
4. Init-time configs passed as the configs argument to Init()

Config file format: one key value pair per line (space-separated).

Built-in Config Files

Located in tessdata/configs/:

Located in tessdata/tessconfigs/:

Key Parameters by Category

Output control:

Recognition control:

Training control:

Internal tuning:

Important

Use tesseract --print-parameters to see the full list of 600+ tunable parameters, including debug flags, classifier thresholds, and layout analysis settings. The -c flag sets non-init parameters only; init parameters must be passed via config files to Init().

Environment Variables

Tessdata File Structure

A .traineddata file is a concatenated archive containing:

Use combine_tessdata -l lang.traineddata to list components and combine_tessdata -u lang.traineddata to unpack them.

4. Deployment & Scaling

CMake Build Options

cmake .. \
  -DBUILD_TRAINING_TOOLS=ON \
  -DBUILD_SHARED_LIBS=ON \
  -DGRAPHICS_DISABLED=ON \
  -DDISABLED_LEGACY_ENGINE=OFF \
  -DENABLE_LTO=ON \
  -DCMAKE_BUILD_TYPE=Release

Note

For production deployments that only need LSTM recognition, enable DISABLED_LEGACY_ENGINE and GRAPHICS_DISABLED to reduce binary size and dependencies.

Autotools Build

./autogen.sh
./configure --disable-graphics --enable-debug=no
make -j$(nproc)
sudo make install

The autogen.sh script requires aclocal, libtoolize (or glibtoolize on macOS), autoconf, autoheader, and automake.

Snap Packaging

The snap/snapcraft.yaml defines a strict-confinement snap:

• Base: core22
• Plugin: autotools
• Build deps: pkg-config, libpng-dev, libjpeg-dev, libtiff-dev, zlib1g-dev, libicu-dev, libpango1.0-dev, libcairo2-dev
• Runtime deps: libgomp1
• Bundled Leptonica: 1.83.1 (built from source)
• Tessdata path: $SNAP_USER_COMMON (user must place .traineddata files here)
• Plugs: home, removable-media (must be connected manually for /media/* access)

Windows CI (AppVeyor)

The appveyor.yml builds on Visual Studio 2022 (Win64, Release) using the sw (Software Network) build tool. Tests for lstm and lstm_recode are skipped in CI.

NSIS Installer (Windows)

The nsis/ directory contains scripts for building a Windows installer:

• tesseract.nsi: NSIS installer script
• find_deps.py: Python script to discover DLL dependencies for bundling
• winpath.cpp: Utility to manage Windows PATH variable
• nsis/include/EnvVarUpdate.nsh: NSIS include for environment variable manipulation

Shared Library Versioning

Warning

Community issue #2749 notes ongoing issues with shared library versioning. When deploying Tesseract as a shared library, verify the SONAME version matches your application's expectations.

5. Operations

Tessdata Management

# List languages available in current tessdata directory
tesseract --list-langs

# Unpack a traineddata file to inspect components
combine_tessdata -u eng.traineddata eng.

# Repack modified components
combine_tessdata eng.

Tip

Keep tessdata_fast models for general use and tessdata_best for batch jobs where accuracy matters more than speed.

Multi-Language Setup

Language data files must match the engine mode:

Batch Processing

For large-volume OCR:

# Create a file list
find /scans/ -name "*.tiff" > filelist.txt

# Process all files
tesseract filelist.txt output pdf --psm 3 -l eng

For parallel processing, split the file list and run multiple Tesseract instances. Each TessBaseAPI instance is thread-safe as long as you do not call SetVariable() on global classify/textord parameters across threads.

Note

Each Tesseract instance loads its own copy of the language model. For high-parallelism workloads, consider the memory impact of loading multiple models simultaneously (approximately 15 MB per language per instance).

Performance Monitoring

The --version output shows which SIMD instruction sets are active. For runtime performance tuning:

• Use --oem 1 (LSTM only) for fastest recognition
• Lower the DPI to 300 (diminishing returns above this)
• Use --psm 6 or more specific modes to reduce layout analysis overhead
• Set --loglevel OFF in production to eliminate stderr I/O

6. Performance

SIMD Acceleration

The LSTM engine's inner loops are dominated by dot products and integer SIMD matrix multiplications. Tesseract dispatches to the best available implementation at runtime:

The dispatch logic lives in src/arch/simddetect.cpp, which uses CPUID (x86) or compile-time flags (ARM/RISC-V) to select the fastest path.

Performance Characteristics

7. Security

Input Handling

Tesseract processes arbitrary image files via Leptonica. Image parsing vulnerabilities in underlying libraries (libtiff, libpng, libjpeg, etc.) apply. Keep image libraries updated.

Warning

Do not expose Tesseract to untrusted input in internet-facing services without sandboxing. The unittest/fuzzers/ directory contains OSS-Fuzz integration for continuous vulnerability discovery, but image parsing libraries remain the primary attack surface.

Memory Safety

• The codebase includes ASan/LSan suppression files (unittest/tesseract_leaksanitizer.supp)
• Community issue #4495 reports an out-of-bounds read in UNICHAR::UTF8ToUTF32 — validate input encoding when processing untrusted text
• The C API (capi.h) requires callers to free returned strings with TessDeleteText() to prevent memory leaks

File System Access

• Tesseract reads from the tessdata directory and the input image path
• Config files are read from tessdata/configs/ and tessdata/tessconfigs/
• With libcurl support, Tesseract can fetch images from URLs (controlled by curl_timeout and curl_cookiefile parameters)
• Output files are written to the working directory at the specified output base path

Caution

The curl_cookiefile parameter allows specifying a cookie file for URL fetching. In multi-tenant environments, ensure this cannot be set to read arbitrary files.

8. Developer Internals

Repository Structure

tesseract/
├── include/tesseract/    # Public API headers (baseapi.h, capi.h, publictypes.h, ...)
├── src/
│   ├── tesseract.cpp     # CLI main entry point
│   ├── svpaint.cpp       # ScrollView paint demo
│   ├── api/              # Output renderers (ALTO, hOCR, PAGE, PDF, TSV, text, box, UNLV)
│   ├── arch/             # SIMD detection and optimized dot product/matrix ops
│   ├── ccmain/           # Core recognition control flow, result iterators, paragraphs
│   ├── ccstruct/         # Core data structures (blobs, blocks, rows, words, images)
│   ├── ccutil/           # Utilities (params, Unicode, serialization, tessdata manager)
│   ├── classify/         # Legacy classifier (adaptive matching, feature extraction)
│   ├── cutil/            # C-era utilities (bit vectors, linked lists)
│   ├── dict/             # Dictionary (DAWG), context checking, hyphenation
│   ├── lstm/             # LSTM neural network layers and beam search decoder
│   ├── textord/          # Page layout analysis (column/line/word finding, tables)
│   ├── training/         # Training tools and libraries
│   │   ├── common/       # Common training library
│   │   ├── pango/        # Pango-based text rendering for training
│   │   └── unicharset/   # Unicode character set utilities, LSTM trainer
│   ├── viewer/           # ScrollView debug visualization
│   └── wordrec/          # Word recognition (segmentation, language model)
├── tessdata/             # Default tessdata directory
│   ├── configs/          # Built-in config files
│   └── tessconfigs/      # Legacy config presets
├── unittest/             # Google Test unit tests
├── cmake/                # CMake build infrastructure
├── doc/                  # Man pages (.asc format)
├── java/                 # ScrollView Java client
├── nsis/                 # Windows NSIS installer scripts
├── snap/                 # Snap packaging
├── test/                 # Test data (images, reference output)
├── CMakeLists.txt        # Primary build file
├── Makefile.am           # Autotools build file
├── configure.ac          # Autotools configuration
└── sw.cpp                # Software Network build file (Windows CI)

Architecture Deep Dive

Recognition Pipeline

1. Image Loading — Leptonica reads the image file. Multi-page TIFFs are handled natively. File lists (one path per line) can be streamed from a text file or stdin.

2. Thresholding — ImageThresholder (src/ccmain/thresholder.cpp) converts the image to binary using Otsu's method (src/ccstruct/otsuthr.cpp). The thresholder normalizes the image for the recognition engine.

3. Page Layout Analysis — The textord/ module performs:

   • Connected component analysis — Edge detection and blob extraction (edgblob, edgloop, scanedg)
   • Column finding — colfind.cpp identifies text columns using ColPartition grids
   • Line finding — linefind.cpp detects horizontal/vertical separator lines
   • Tab detection — tabfind.cpp, tabvector.cpp detect tab stops for column alignment
   • Text ordering — textord.cpp organizes blobs into rows, then rows into blocks
   • Table detection — tablefind.cpp, tablerecog.cpp recognize tabular layouts
   • Baseline detection — baselinedetect.cpp fits baselines to text rows

4. Word Segmentation — The wordrec/ module segments blobs into words:

   • Chopping — chop.cpp, chopper.cpp split poorly-segmented characters
   • Seam finding — findseam.cpp determines optimal character boundaries
   • Language model — language_model.cpp evaluates word hypotheses

5. Recognition — Two engines, selectable via OEM:

   • LSTM — lstm/lstmrecognizer.cpp runs the neural network. The network is a series of layers (convolve, LSTM, fully connected, maxpool, parallel, series, reversed) defined in lstm/network.h. Beam search decoding (recodebeam.cpp) produces the final text.
   • Legacy — classify/adaptmatch.cpp uses feature extraction (intfx.cpp, mfx.cpp) and integer template matching (intmatcher.cpp). The adaptive classifier learns from confident results during recognition.

6. Post-Processing — ccmain/ handles:

   • Paragraph detection — paragraphs.cpp groups lines into paragraphs
   • Superscript/subscript — superscript.cpp detects sup/sub
   • Reject mapping — reject.cpp handles uncertain characters
   • Fix spacing — fixspace.cpp corrects inter-word spacing
   • Equation detection — equationdetect.cpp identifies math expressions

7. Output Rendering — src/api/ renderers format results:

   • Each renderer implements BeginDocumentHandler, AddImageHandler, EndDocumentHandler
   • Renderers are chained via insert() — the first renderer owns the chain
   • PDF rendering embeds a font (tessdata/pdf.ttf) for invisible text layer

LSTM Network Architecture

The LSTM engine uses a configurable network topology specified as a string (e.g., [1,36,0,1 Ct3,3,16 Mp3,3 Lfys48 Lfx96 Lrx96 Lfx256 O1c111]). The network components:

The network builder (training/common/networkbuilder.cpp) parses the network specification string and constructs the layer graph.

Parameter System

All Tesseract parameters are defined as static typed variables using macros:

• BOOL_VAR(name, default, description) — Boolean parameter
• INT_VAR(name, default, description) — Integer parameter
• DOUBLE_VAR(name, default, description) — Double parameter
• STRING_VAR(name, default, description) — String parameter

Parameters are registered globally and accessed via ParamUtils::SetParam() / ParamUtils::GetParam(). Each Tesseract instance has its own parameter scope (tesseract_->params()), but some parameters in classify/ and textord/ are global and affect all instances.

Tessdata Manager

src/ccutil/tessdatamanager.cpp manages .traineddata files, which are custom archive formats containing multiple named components. The manager supports:

• Direct file reading from a tessdata directory
• In-memory initialization from a byte array
• Loading from an archive file (with libarchive support)
• Component extraction and recombination

Module Reference

src/api/ — Output Renderers (10 files, 222K chars)

src/lstm/ — Neural Network Engine (37 files, 569K chars)

Core LSTM recognition engine. Key files:

• lstmrecognizer.cpp/h — Top-level LSTM recognition interface
• recodebeam.cpp/h — Beam search decoder for LSTM output
• lstm.cpp/h — LSTM cell implementation (forward/backward propagation)
• fullyconnected.cpp/h — Dense layer with various activation functions
• network.cpp/h — Base network class, serialization, network type enum
• networkio.cpp/h — Network I/O data handling
• convolve.cpp/h — Convolutional layer
• weightmatrix.cpp/h — Weight matrix operations with SIMD dispatch
• stridemap.cpp/h — Stride map for 2D-to-1D mapping

src/textord/ — Page Layout Analysis (79 files, 1.67M chars)

The largest module. Key subsystems:

• Column analysis: colfind.cpp, colpartition.cpp, colpartitiongrid.cpp
• Line detection: linefind.cpp, alignedblob.cpp, baselinedetect.cpp
• Tab detection: tabfind.cpp, tabvector.cpp
• Table recognition: tablefind.cpp, tablerecog.cpp
• Text ordering: textord.cpp, makerow.cpp, wordseg.cpp
• Stroke analysis: strokewidth.cpp, ccnontextdetect.cpp
• CJK support: cjkpitch.cpp (CJK fixed-pitch detection)
• Devanagari: devanagari_processing.cpp (Indic script handling)
• Image detection: imagefind.cpp (find non-text regions)

src/classify/ — Legacy Classifier (54 files, 614K chars)

Pattern-based character classifier (pre-LSTM). Key files:

• adaptmatch.cpp — Adaptive matching (learns during recognition)
• intmatcher.cpp/h — Integer template matcher (core classification)
• intproto.cpp/h — Integer prototype data structures
• classify.cpp/h — Classify class (orchestrates classification)
• shapetable.cpp/h — Shape classification table
• cluster.cpp/h — Clustering algorithms for training
• trainingsample.cpp/h — Training sample management

src/ccmain/ — Recognition Control (45 files, 767K chars)

Orchestrates the full recognition pipeline:

• tesseractclass.cpp/h — Tesseract class (inherits from Classify, Dict, etc.)
• control.cpp — Main recognition control flow
• pagesegmain.cpp — Page segmentation entry point
• paragraphs.cpp — Paragraph detection and grouping
• resultiterator.cpp — Result traversal iterator
• pageiterator.cpp — Page layout traversal iterator
• ltrresultiterator.cpp — Left-to-right result iterator
• thresholder.cpp — Image thresholding
• osdetect.cpp — Orientation and script detection

src/ccutil/ — Core Utilities (44 files, 774K chars)

• params.cpp/h — Parameter system (typed variables, set/get)
• unicharset.cpp/h — Unicode character set management
• unichar.cpp — Single Unicode character representation
• unicharcompress.cpp/h — Unicode compression for LSTM
• serialis.cpp/h — Binary serialization (TFile class)
• tessdatamanager.cpp/h — .traineddata archive management
• tprintf.cpp/h — Formatted printing with log levels
• errcode.cpp/h — Error handling and assertion macros
• scanutils.cpp/h — Portable scanning utilities

src/ccstruct/ — Core Data Structures (77 files, 876K chars)

• pageres.cpp/h — Page results (blocks, rows, words, characters)
• blobbox.cpp/h — Bounding-box blob representation
• blobs.cpp/h — Blob data (outlines, fragments)
• werd.cpp/h — Word representation
• ocrblock.cpp/h — Text block representation
• ocrrow.cpp/h — Text row representation
• imagedata.cpp/h — Training image data
• otsuthr.cpp/h — Otsu thresholding algorithm
• matrix.cpp/h — Matrix operations
• ratngs.cpp/h — Word choice ratings

src/dict/ — Dictionary (14 files, 192K chars)

• dict.cpp/h — Dictionary class (permuter, word validation)
• dawg.cpp/h — Directed Acyclic Word Graph implementation
• dawg_cache.cpp/h — Global DAWG cache (shared across instances)
• trie.cpp/h — Trie data structure (used to build DAWGs)
• stopper.cpp/h — Word stopping criteria
• permdawg.cpp — Permutation DAWG search
• context.cpp — Context-based word validation
• hyphen.cpp — Hyphenation handling

src/arch/ — SIMD Dispatch (15 files, 90K chars)

Runtime SIMD detection and optimized implementations:

• simddetect.cpp/h — CPU feature detection (CPUID-based)
• dotproduct.cpp — Scalar fallback
• dotproductsse.cpp — SSE4.1 implementation
• dotproductavx.cpp — AVX implementation
• dotproductavx512.cpp — AVX-512F implementation
• dotproductfma.cpp — FMA implementation
• dotproductneon.cpp — ARM NEON implementation
• intsimdmatrix.cpp/h — Integer SIMD matrix base
• intsimdmatrixsse.cpp — SSE implementation
• intsimdmatrixavx2.cpp — AVX2 implementation
• intsimdmatrixneon.cpp — NEON implementation
• intsimdmatrixrvv.cpp — RISC-V Vector implementation

Training Tools

Training libraries:

Code Patterns and Conventions

Namespace: All code resides in the tesseract namespace.

Memory management: Raw new/delete in older code; std::unique_ptr in newer code. The C API requires explicit TessDeleteText() calls for returned strings.

Error handling: ASSERT_HOST() for invariants, return codes for recoverable errors. The errcode.cpp module defines error severity levels.

Conditional compilation:

• DISABLED_LEGACY_ENGINE — Removes legacy classifier, OSD, and related code
• GRAPHICS_DISABLED — Removes ScrollView debug visualization
• HAVE_CONFIG_H — Autotools configuration header
• _OPENMP — OpenMP parallelism
• HAVE_LIBARCHIVE, HAVE_LIBCURL — Optional feature support

Parameter naming: Snake case with module prefix (e.g., tessedit_, classify_, textord_).

List macros: The codebase uses custom list macros (ELISTIZE, CLISTIZE, ELIST2IZE) in src/ccutil/elst.h, clst.h, elst2.h for intrusive linked lists — a legacy pattern from the original HP codebase.

Testing Strategy

The unittest/ directory contains 60+ Google Test test suites covering:

Fuzz testing via OSS-Fuzz (unittest/fuzzers/fuzzer-api.cpp).

Run tests:

cd build
cmake .. -DBUILD_TRAINING_TOOLS=ON
make -j$(nproc)
ctest --output-on-failure

Note

Tests require test data from the tessdata_unittest repository (tessdata + fonts). Clone it alongside the tesseract source or set TESSDATA_DIR, TESTING_DIR, and TESTDATA_DIR environment variables.

Public API Reference (C++)

The primary API class is TessBaseAPI (defined in include/tesseract/baseapi.h):

Initialization:

Image handling:

Recognition:

Results:

Iterator hierarchy:

PageIterator → LTRResultIterator → ResultIterator

Traverse at levels: RIL_BLOCK → RIL_PARA → RIL_TEXTLINE → RIL_WORD → RIL_SYMBOL

Each level provides bounding boxes, confidence, font attributes, and recognition language.

Contributing

• License: Apache 2.0
• Build: CMake (primary) or Autotools
• Code style: .clang-format is included in the repository
• Testing: Add Google Test cases in unittest/ for new functionality
• CI: AppVeyor (Windows), GitHub Actions (Linux/macOS)
• Language: C++17 standard required

9. Integration Points

C API

The C API (include/tesseract/capi.h) provides a complete wrapper for language bindings:

#include <tesseract/capi.h>

TessBaseAPI *api = TessBaseAPICreate();
TessBaseAPIInit3(api, "/usr/share/tesseract-ocr/5/tessdata", "eng");

Pix *image = pixRead("input.png");
TessBaseAPISetImage2(api, image);

char *text = TessBaseAPIGetUTF8Text(api);
printf("%s", text);

TessDeleteText(text);
pixDestroy(&image);
TessBaseAPIEnd(api);
TessBaseAPIDelete(api);

Progress Monitoring

The ETEXT_DESC structure enables progress callbacks and cancellation:

ETEXT_DESC monitor;
monitor.cancel = my_cancel_func;      // Return true to cancel
monitor.progress_callback = my_progress_func;
monitor.deadline_msecs = 10000;       // 10-second timeout
api.Recognize(&monitor);

Renderer Chaining

Multiple output formats can be produced in a single pass by chaining renderers:

auto text_renderer = std::make_unique<TessTextRenderer>("output");
auto pdf_renderer = std::make_unique<TessPDFRenderer>("output", datapath, false);
text_renderer->insert(pdf_renderer.get());
api.ProcessPages("input.tiff", nullptr, 0, text_renderer.get());

ScrollView Debug Visualization

When built with graphics enabled (GRAPHICS_DISABLED not defined), Tesseract can display intermediate results via the ScrollView Java client (java/com/google/scrollview/). The client communicates over a TCP socket.

The svpaint executable (src/svpaint.cpp) is a standalone ScrollView demo application.