# 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

| Component | Path | Role |
|---|---|---|
| CLI entry point | `src/tesseract.cpp` | Main executable: argument parsing, renderer setup, recognition loop |
| Public C++ API | `include/tesseract/baseapi.h` | `TessBaseAPI` class: init, image handling, recognition, text retrieval |
| Public C API | `include/tesseract/capi.h` | C-compatible wrapper around `TessBaseAPI` |
| Output renderers | `src/api/` | Text, hOCR, ALTO XML, PAGE XML, TSV, PDF, UNLV, Box renderers |
| LSTM recognizer | `src/lstm/` | Neural network layers, beam search decoder, LSTM recognizer |
| Legacy classifier | `src/classify/` | Adaptive classifier, feature extraction, shape tables |
| Page layout | `src/textord/` | Column/line/word finding, tab detection, table recognition |
| Core structures | `src/ccstruct/` | Blobs, blocks, rows, words, page results, image thresholding |
| Core utilities | `src/ccutil/` | Params system, Unicode handling, serialization, tessdata manager |
| Main control | `src/ccmain/` | Recognition control flow, paragraphs, result iterators |
| Dictionary | `src/dict/` | DAWG-based dictionary, context checking, hyphenation |
| Word recognition | `src/wordrec/` | Word segmentation, language model, seam finding |
| SIMD detection | `src/arch/` | Runtime SIMD dispatch (AVX512/AVX2/AVX/FMA/SSE4.1/NEON/RVV) |
| C utilities | `src/cutil/` | Bit vectors, linked lists (legacy C code) |
| Training tools | `src/training/` | 15 training executables + common/pango/unicharset libraries |
| ScrollView | `src/viewer/` | Debug visualization via Java ScrollView client |
| Public types | `include/tesseract/publictypes.h` | Enums: `PageSegMode`, `OcrEngineMode`, `PageIteratorLevel`, etc. |
| Iterators | `include/tesseract/pageiterator.h`, `resultiterator.h` | Page/result traversal at block/paragraph/line/word/symbol levels |

### Technology Stack

| Technology | Version/Detail | Purpose |
|---|---|---|
| C++ | C++17 standard | Core language |
| Leptonica | ≥1.74 | Image I/O and manipulation (required dependency) |
| ICU | Unicode library | Unicode normalization in training tools |
| Pango/Cairo | Font rendering | `text2image` training tool (optional) |
| libarchive | Archive reading | Loading `.traineddata` from archives (optional) |
| libcurl | HTTP client | Fetching images from URLs (optional) |
| libtiff | TIFF support | Multi-page TIFF handling |
| OpenMP | Parallelism | Optional SIMD and parallel processing |
| CMake / Autotools | Build systems | Both supported (CMake is primary) |
| Google Test | Testing framework | Unit tests in `unittest/` |
| sw (Software Network) | Build system | Windows CI builds (AppVeyor) |

## 2. System Requirements

### Build Requirements

| Requirement | Minimum | Recommended |
|---|---|---|
| **C++ Compiler** | C++17 (GCC 7, Clang 5, MSVC 2019) | GCC 12+ or Clang 15+ |
| **CMake** | 3.10 | 3.20+ |
| **Leptonica** | 1.74 | 1.84+ |
| **ICU** | Required for training tools | Latest stable |
| **Pango + Cairo** | Required for `text2image` | Latest stable |
| **pkg-config** | Required for autotools build | N/A |

### Build Dependencies (Debian/Ubuntu)

```bash
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

| Requirement | Details |
|---|---|
| **Leptonica** | Shared library (`liblept.so` / `liblept.dylib` / `lept.dll`) |
| **Tessdata** | At least one `.traineddata` file in the tessdata directory |
| **CPU** | SSE4.1 recommended for LSTM acceleration; AVX2/AVX512 for best performance |
| **Memory** | ~100 MB base + ~15 MB per loaded language model |

### SIMD Support Matrix

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

| Architecture | Instruction Sets | Detection |
|---|---|---|
| x86-64 | AVX512VNNI, AVX512BW, AVX512F, AVX2, AVX, FMA, SSE4.1 | `SIMDDetect` in `src/arch/simddetect.cpp` |
| ARM64 | NEON | Compile-time `HAVE_NEON` / `__aarch64__` |
| RISC-V | RVV (Vector) | Compile-time `HAVE_RVV` |

> [!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/`:

| File | Variables Set |
|---|---|
| `alto` | `tessedit_create_alto 1` |
| `hocr` | `tessedit_create_hocr 1` |
| `pdf` | `tessedit_create_pdf 1` |
| `tsv` | `tessedit_create_tsv 1` |
| `txt` | `tessedit_create_txt 1` |
| `quiet` | Suppresses messages |
| `digits` | `tessedit_char_whitelist 0123456789.-` |
| `makebox` | `tessedit_create_boxfile 1` |
| `lstmbox` | `tessedit_create_lstmbox 1` |
| `wordstrbox` | `tessedit_create_wordstrbox 1` |
| `lstm.train` | `tessedit_train_line_recognizer 1` |
| `box.train` | `tessedit_resegment_from_boxes 1` |
| `box.train.stderr` | `tessedit_resegment_from_boxes 1` + error output to stderr |
| `linebox` | `tessedit_make_boxes_from_boxes 1` |
| `logfile` | Enables file-based logging |
| `unlv` | `tessedit_write_unlv 1` |
| `page` | `tessedit_create_page_xml 1` |
| `inter` | Interactive debugging mode |
| `bazaar` | Bazaar-specific settings |
| `bigram` | Bigram language model settings |
| `kannada` | Kannada-specific settings |
| `strokewidth` | Stroke width analysis |
| `get.images` | Save intermediate images |
| `api_config` | API-specific defaults |
| `ambigs.train` | `tessedit_ambigs_training 1` |
| `rebox` | Rebox mode |
| `lstmdebug` | LSTM debug output |

Located in `tessdata/tessconfigs/`:

| File | Purpose |
|---|---|
| `batch` | Batch processing settings |
| `batch.nochop` | Batch mode without chopping |
| `matdemo` | Matrix demo settings |
| `msdemo` | Microsoft demo settings |
| `nobatch` | Non-batch mode |
| `segdemo` | Segmentation demo settings |

### Key Parameters by Category

**Output control:**

| Parameter | Type | Default | Description |
|---|---|---|---|
| `tessedit_create_txt` | bool | true (fallback) | Create plain text output |
| `tessedit_create_hocr` | bool | false | Create hOCR output |
| `tessedit_create_alto` | bool | false | Create ALTO XML output |
| `tessedit_create_page_xml` | bool | false | Create PAGE XML output |
| `tessedit_create_tsv` | bool | false | Create TSV output |
| `tessedit_create_pdf` | bool | false | Create searchable PDF output |
| `tessedit_create_lstmbox` | bool | false | Create LSTM box file |
| `tessedit_create_boxfile` | bool | false | Create box file |
| `tessedit_create_wordstrbox` | bool | false | Create WordStr box file |
| `tessedit_write_unlv` | bool | false | Create UNLV output |
| `textonly_pdf` | bool | false | PDF with invisible text only (no image layer) |
| `hocr_font_info` | bool | false | Include font info in hOCR/TSV |
| `document_title` | string | "" | Title for hOCR and PDF output |

**Recognition control:**

| Parameter | Type | Default | Description |
|---|---|---|---|
| `tessedit_char_whitelist` | string | "" | Only recognize these characters |
| `tessedit_char_blacklist` | string | "" | Never recognize these characters |
| `tessedit_pageseg_mode` | int | 3 (PSM_AUTO) | Page segmentation mode |
| `user_defined_dpi` | int | 0 | Override image DPI |
| `user_words_file` | string | "" | Path to user word list |
| `user_patterns_file` | string | "" | Path to user patterns file |
| `tessedit_page_number` | int | -1 | Process only this page (multi-page input) |

**Training control:**

| Parameter | Type | Default | Description |
|---|---|---|---|
| `tessedit_ambigs_training` | bool | false | Ambiguous words training mode |
| `tessedit_resegment_from_boxes` | bool | false | Resegment using box files |
| `tessedit_make_boxes_from_boxes` | bool | false | Create boxes from existing boxes |
| `tessedit_train_line_recognizer` | bool | false | LSTM line recognizer training mode |

**Internal tuning:**

| Parameter | Type | Default | Description |
|---|---|---|---|
| `classify_bln_numeric_mode` | bool | false | Numeric-only classification mode |
| `stream_filelist` | bool | false | Read file list from stdin |
| `unlv_tilde_crunching` | bool | false | Enable UNLV tilde crunching |
| `classify_font_name` | string | "UnknownFont" | Default font name for training |

> [!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

| Variable | Description |
|---|---|
| `TESSDATA_PREFIX` | Path to the directory containing `.traineddata` files |
| `LEPT_MSG_SEVERITY` | Leptonica log level (when set, Tesseract uses `L_SEVERITY_EXTERNAL`) |

### Tessdata File Structure

A `.traineddata` file is a concatenated archive containing:

| Component | Content |
|---|---|
| `config` | Default configuration |
| `unicharset` | Character set definition |
| `unicharambigs` | Character ambiguities |
| `inttemp` | Integer templates (legacy engine) |
| `pffmtable` | Feature table (legacy engine) |
| `normproto` | Normalization prototypes (legacy engine) |
| `shapetable` | Shape classification table (legacy engine) |
| `lstm` | LSTM network weights |
| `lstm-punc-dawg` | Punctuation DAWG |
| `lstm-word-dawg` | Word DAWG |
| `lstm-number-dawg` | Number pattern DAWG |
| `version` | Model version string |

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

## 4. Deployment & Scaling

### CMake Build Options

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

| Option | Default | Description |
|---|---|---|
| `BUILD_TRAINING_TOOLS` | OFF | Build training executables |
| `BUILD_SHARED_LIBS` | ON | Build as shared library |
| `GRAPHICS_DISABLED` | OFF | Disable ScrollView debug graphics (removes Java dependency) |
| `DISABLED_LEGACY_ENGINE` | OFF | Build LSTM-only (smaller binary, no OSD) |
| `ENABLE_LTO` | OFF | Link-time optimization |
| `CMAKE_INSTALL_PREFIX` | `/usr/local` | Installation prefix |

> [!NOTE]
> For production deployments that only need LSTM recognition, enable `DISABLED_LEGACY_ENGINE` and `GRAPHICS_DISABLED` to reduce binary size and dependencies.

### Autotools Build

```bash
./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

```bash
# 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:

| Engine Mode | Compatible Tessdata |
|---|---|
| `--oem 0` (legacy) | `tessdata` only |
| `--oem 1` (LSTM) | `tessdata_fast`, `tessdata_best`, `tessdata` |
| `--oem 2` (combined) | `tessdata` only |
| `--oem 3` (default) | Any (uses what's available) |

### Batch Processing

For large-volume OCR:

```bash
# 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:

| Function | Implementations | Source Files |
|---|---|---|
| `DotProduct` | Native, SSE, AVX, AVX512F, FMA, NEON | `src/arch/dotproduct*.cpp` |
| `IntSimdMatrix` | Generic, SSE, AVX2, NEON, RVV | `src/arch/intsimdmatrix*.cpp` |

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

| Factor | Impact |
|---|---|
| Image DPI | 300 DPI is optimal; higher increases processing time without proportional accuracy gains |
| PSM mode | `--psm 3` (auto) is most expensive; specific modes (`6`, `7`, `8`) are faster |
| Engine mode | LSTM only (`--oem 1`) is faster than combined (`--oem 2`) |
| Languages loaded | Each additional language increases recognition time |
| Image size | Processing is roughly linear with pixel count |
| SIMD level | AVX2 provides ~2-4x speedup over scalar; AVX512 provides ~1.5x over AVX2 |

## 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:

| Layer Type | Class | Purpose |
|---|---|---|
| Convolve | `Convolve` | Stacks inputs over a rectangle |
| LSTM | `LSTM` | Bidirectional LSTM cells |
| FullyConnected | `FullyConnected` | Dense layer with softmax/tanh/relu |
| MaxPool | `Maxpool` | Max pooling |
| Parallel | `Parallel` | Run networks in parallel |
| Series | `Series` | Sequential network stack |
| Reversed | `Reversed` | Reverse input sequence for bidirectional |
| Reconfig | `Reconfig` | Resize stride map |
| Input | `Input` | Input layer |

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)

| File | Class | Output Format |
|---|---|---|
| `altorenderer.cpp` | `TessAltoRenderer` | ALTO XML (Library of Congress standard) |
| `hocrrenderer.cpp` | `TessHOcrRenderer` | hOCR (HTML with OCR metadata) |
| `pagerenderer.cpp` | `TessPAGERenderer` | PAGE XML (PRImA format) |
| `pdfrenderer.cpp` | `TessPDFRenderer` | Searchable PDF with embedded font |
| `renderer.cpp` | `TessResultRenderer` | Base renderer class, text renderer |
| `lstmboxrenderer.cpp` | `TessLSTMBoxRenderer` | LSTM box files for training |
| `wordstrboxrenderer.cpp` | `TessWordStrBoxRenderer` | WordStr box files for training |
| `baseapi.cpp` | `TessBaseAPI` | Core API implementation (2000+ lines) |
| `capi.cpp` | C wrappers | C-compatible API functions |
| `pdf_ttf.h` | — | Embedded PDF font data |

#### `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

| Tool | Source | Purpose |
|---|---|---|
| `text2image` | `src/training/text2image.cpp` | Render text to images for training (requires Pango) |
| `lstmtraining` | `src/training/lstmtraining.cpp` | Train LSTM networks |
| `lstmeval` | `src/training/lstmeval.cpp` | Evaluate LSTM model accuracy |
| `combine_tessdata` | `src/training/combine_tessdata.cpp` | Pack/unpack `.traineddata` files |
| `combine_lang_model` | `src/training/combine_lang_model.cpp` | Combine language model components |
| `unicharset_extractor` | `src/training/unicharset_extractor.cpp` | Extract character set from training data |
| `set_unicharset_properties` | `src/training/set_unicharset_properties.cpp` | Set Unicode properties on character set |
| `merge_unicharsets` | `src/training/merge_unicharsets.cpp` | Merge multiple character sets |
| `mftraining` | `src/training/mftraining.cpp` | Train legacy micro-feature classifier |
| `cntraining` | `src/training/cntraining.cpp` | Generate normalization prototypes (legacy) |
| `shapeclustering` | `src/training/shapeclustering.cpp` | Cluster shape features (legacy) |
| `classifier_tester` | `src/training/classifier_tester.cpp` | Test classifier accuracy |
| `ambiguous_words` | `src/training/ambiguous_words.cpp` | Find ambiguous words in dictionary |
| `wordlist2dawg` | `src/training/wordlist2dawg.cpp` | Convert word list to DAWG |
| `dawg2wordlist` | `src/training/dawg2wordlist.cpp` | Convert DAWG back to word list |

Training libraries:

| Library | Path | Dependencies |
|---|---|---|
| `common_training` | `src/training/common/` | `libtesseract` |
| `unicharset_training` | `src/training/unicharset/` | `common_training`, ICU |
| `pango_training` | `src/training/pango/` | `unicharset_training`, Pango, Cairo |

### 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:

| Test Category | Examples | Coverage |
|---|---|---|
| API tests | `apiexample_test`, `baseapi_test`, `baseapi_thread_test`, `cleanapi_test` | C/C++ API correctness |
| C API tests | `capiexample_test`, `capiexample_c_test` | C-compatibility layer |
| LSTM tests | `lstm_test`, `lstm_recode_test`, `lstm_squashed_test`, `lstmtrainer_test` | Neural network |
| Layout tests | `layout_test`, `colpartition_test`, `tablefind_test`, `tablerecog_test` | Page analysis |
| Data structure tests | `rect_test`, `matrix_test`, `bitvector_test`, `heap_test` | Core structures |
| Unicode tests | `unichar_test`, `unicharset_test`, `unicharcompress_test`, `normstrngs_test` | Character handling |
| Validation tests | `validate_grapheme_test`, `validate_indic_test`, `validate_khmer_test`, `validate_myanmar_test` | Script validation |
| Integration | `pagesegmode_test`, `osd_test`, `resultiterator_test`, `progress_test` | End-to-end |

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

Run tests:

```bash
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:**

| Method | Description |
|---|---|
| `Init(datapath, language, mode)` | Initialize engine with tessdata path, language, and engine mode |
| `Init(data, data_size, language, mode, ...)` | Initialize from in-memory traineddata |
| `SetVariable(name, value)` | Set a parameter (after Init, non-init only) |
| `ReadConfigFile(filename)` | Read a config file |
| `End()` | Free all recognition data |

**Image handling:**

| Method | Description |
|---|---|
| `SetImage(pix)` | Set input image (Pix from Leptonica) |
| `SetImage(data, width, height, bpp, bpl)` | Set input image from raw buffer |
| `SetRectangle(left, top, width, height)` | Restrict recognition to a sub-rectangle |
| `SetSourceResolution(ppi)` | Set image resolution for font size calculation |

**Recognition:**

| Method | Description |
|---|---|
| `Recognize(monitor)` | Run recognition (optional, called automatically) |
| `ProcessPages(filename, retry, timeout, renderer)` | Process multiple pages with renderer |
| `ProcessPage(pix, page_index, filename, retry, timeout, renderer)` | Process a single page |
| `AnalyseLayout()` | Run layout analysis only |

**Results:**

| Method | Description |
|---|---|
| `GetUTF8Text()` | Get plain text (caller must `delete[]`) |
| `GetHOCRText(page_number)` | Get hOCR formatted text |
| `GetAltoText(page_number)` | Get ALTO XML text |
| `GetPAGEText(page_number)` | Get PAGE XML text |
| `GetTSVText(page_number)` | Get TSV formatted text |
| `GetBoxText(page_number)` | Get box file text |
| `GetLSTMBoxText(page_number)` | Get LSTM box text |
| `GetWordStrBoxText(page_number)` | Get WordStr box text |
| `GetUNLVText()` | Get UNLV formatted text |
| `GetIterator()` | Get `ResultIterator` for detailed traversal |
| `MeanTextConf()` | Get average confidence (0-100) |
| `AllWordConfidences()` | Get array of per-word confidences |
| `DetectOrientationScript(...)` | Detect script and orientation |

**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:

```c
#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:

```cpp
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:

```cpp
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.

---

_Generated May 2026 from tesseract-ocr/tesseract at 78a8ac8. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._