DOCSEARCHbyAlgolia
Submit Docs

Tesseract OCR

repository·main·Indexed 13 days ago

https://github.com/tesseract-ocr/tesseract

A versatile optical character recognition engine providing a command-line tool and the libtesseract development library. It supports LSTM-based neural networks, over 100 languages, and multiple output formats including plain text, PDF, hOCR, and ALTO. The project offers C and C++ APIs for integration, as well as tools for image thresholding and a hierarchical page result structure (PAGE_RES, BLOCK_RES, ROW_RES, WERD_RES) for granular text extraction.

Tokens
4.7K
Snippets
15
Records
23
Agent score
98%

What's inside Tesseract

  1. Overview of Tesseract OCR

    main

    Tesseract OCR consists of two main components: libtesseract (the OCR engine) and the tesseract command-line program.

    Key features include:

    • Dual Engine Support: Uses a neural net (LSTM) based engine for line recognition (introduced in Tesseract 4) and supports a legacy engine (Tesseract 3) for character pattern recognition. To use the legacy engine, use the --oem 0 flag.
    • Language Support: Supports Unicode (UTF-8) and over 100 languages out of the box.
    • Input Formats: Supports various image formats including PNG, JPEG, and TIFF.
    • Output Formats: Can output to plain text, hOCR (HTML), PDF, invisible-text-only PDF, TSV, ALTO, and PAGE.
    • Extensibility: Can be trained to recognize new languages.

  2. Run Tesseract unit tests

    main

    To execute the unit tests for Tesseract, you must prepare the environment by regenerating build files, initializing submodules, and setting up the required tessdata directory. You must also set the TESSDATA_PREFIX environment variable to point to your tessdata directory before running the tests.

    Follow these steps within the tesseract folder:

    1. Regenerate build files using autoreconf.
    2. Initialize git submodules.
    3. Clone the tessdata_unittest repository to obtain necessary test data.
    4. Copy required fonts to the test directory.
    5. Move the test data into the appropriate directory structure.
    6. Set TESSDATA_PREFIX.
    7. Run make check.
    autoreconf -fiv
git submodule update --init
git clone https://github.com/egorpugin/tessdata tessdata_unittest --depth 1
cp tessdata_unittest/fonts/* test/testing/
mv tessdata_unittest/* ../
export TESSDATA_PREFIX=/prefix/to/path/to/tessdata
make check

  4. Install Tesseract OCR

    main

    You can install Tesseract using one of two methods:

    1. Pre-built binary packages: Use your operating system's package manager to install a ready-to-use version.
    2. Build from source: Compile the code manually. If building from source, ensure your system has a supported compiler installed.

  5. Build Tesseract from source using autotools (Linux/Unix/msys)

    main

    If you have cloned the Tesseract repository from GitHub, you must generate the configure script using autogen.sh.

    Prerequisites:

    • Remove any existing Tesseract 4.0x installations before building.
    • Leptonica: Version 1.74.2 or higher is required.
    • Training Tool Dependencies (excluding Leptonica):
      • A C++ compiler with C++17 support
      • automake
      • pkg-config
      • pango-devel
      • cairo-devel
      • icu-devel

    Build Steps:

    1. Generate configuration files.
    2. Configure the build environment.
    3. Compile the source.
    4. Install the binaries.
    5. Update the shared library cache.
    6. (Optional) Build and install training tools.
    ./autogen.sh
./configure
make
sudo make install
sudo ldconfig
make training
sudo make training-install

  6. Requirements for Tesseract unit testing

    main

    Running Tesseract unit tests requires specific directory structures and font files to ensure correct OCR behavior across different languages and scripts.

    Required Directory Structure

    The test environment expects the following data directories to be present:

    • langdata_lstm: Contains language-specific LSTM data (e.g., eng, hin, kan, kor).
    • tessdata: Standard traineddata files.
    • tessdata_best: High-accuracy traineddata files.
    • tessdata_fast: Fast-inference traineddata files.

    Required Fonts

    You must have the following fonts installed or available in the test directory:

    • Microsoft fonts: arialbi.ttf, times.ttf, verdana.ttf
    • Arabic: ae_Arab.ttf
    • DejaVu: DejaVuSans-ExtraLight.ttf
    • Hindi: Lohit-Hindi.ttf
    • Korean: UnBatang.ttf

  7. Configure TESSDATA_PREFIX for language data

    main

    To run Tesseract, you must install at least the English language and OSD (Orientation and Script Detection) traineddata files into the directory specified by the TESSDATA_PREFIX environment variable.

    You can download individual language files using tools like wget, curl, or a web browser.

    Note for Packagers: While all language data files are available in the tesseract-ocr/tessdata git repository, the repository is large (>1.2 GB). Users should generally download only the specific languages they need.

    git clone https://github.com/tesseract-ocr/tessdata.git tesseract-ocr.tessdata

  8. Understand the Tesseract Page Result Hierarchy

    main

    Tesseract organizes OCR results into a hierarchical structure that mirrors the physical layout of a page. When consuming OCR output via the API, you will navigate through these levels:

    1. PAGE_RES: The top-level container for an entire page. It contains aggregate statistics like char_count, rej_count (rejected characters), and a list of blocks.
    2. BLOCK_RES: Represents a logical block of text (e.g., a paragraph or a column). It contains metadata like font_class, row_count, and x_height, and a list of rows.
    3. ROW_RES: Represents a single line of text within a block. It contains character counts and a list of words.
    4. WERD_RES: Represents an individual word. This is the most granular level of result, containing the recognized text, bounding boxes, and confidence/rating information.

  9. Build ScrollView.jar for Java

    main

    To compile ScrollView.jar, you need an active internet connection and curl. The build process automatically downloads several dependencies (piccolo2d-core-3.0.1.jar, piccolo2d-extras-3.0.1.jar, and jaxb-api-2.3.1.jar) and places them in the tesseract/java directory.

    make ScrollView.jar

  10. Use libtesseract API for development

    main

    Developers can integrate Tesseract into their own applications using the libtesseract library. The project provides both C and C++ APIs:

    • C API: Available via capi.h.
    • C++ API: Available via baseapi.h.

    For other programming languages, look for available wrappers in the Tesseract AddOns documentation. Detailed API documentation is generated via Doxygen and is available online.

  11. Run Tesseract via Command Line

    main

    The basic syntax for the Tesseract command-line tool is:

    tesseract <imagename> <outputbase> [-l <lang>] [--oem <ocrengine-mode>] [--psm <pagesegmode>] [configfiles...]

    • imagename: The input image file.
    • outputbase: The base name for the output file (the extension will be added based on the format).
    • -l <lang>: Specify the language(s) to use.
    • --oem <ocrengine-mode>: Set the OCR engine mode (e.g., --oem 0 for legacy engine).
    • --psm <pagesegmode>: Set the Page Segmentation Mode.
    • configfiles...: Additional configuration files.

    Use tesseract --help or man tesseract for a full list of available options.

    tesseract imagename outputbase [-l lang] [--oem ocrenginemode] [--psm pagesegmode] [configfiles...]

  12. Iterate through page results using PAGE_RES_IT

    main

    To traverse the recognized content of a page, use the PAGE_RES_IT iterator. This iterator allows you to move through words, rows, and blocks sequentially.

    Key Navigation Methods:

    • forward(): Moves to the next word.
    • forward_paragraph(): Moves to the first word in the next non-empty paragraph.
    • forward_block(): Moves to the first word in the next block.
    • restart_page(): Restarts iteration from the beginning of the page (skipping empty blocks).
    • restart_row(): Restarts iteration at the beginning of the current row.

    Accessing Current Context: While iterating, you can retrieve the current structural context using:

    • word(): Returns the current WERD_RES*.
    • row(): Returns the current ROW_RES*.
    • block(): Returns the current BLOCK_RES*.
    // Example: Iterating through all words in a page
tesseract::PAGE_RES_IT it(my_page_res);
while (auto* werd = it.forward()) {
    // Process each word
    const char* text = werd->BestUTF8(0, false);
    // ...
}