OCR with Tesseract

The 4.x migration converter rewrites 3.x XML for you, including the old otherTesseractSettings list. The 3.x forms are shown in labelled blocks below where they help to read old configuration.

Each language is a .traineddata file in a tessdata directory. Three sets are published by the Tesseract project: tessdata_fast (smaller and faster, what most distribution packages ship), tessdata_best (slower, more accurate) and the legacy tessdata (also needed for the legacy engine mode). Script models such as Latin read every language of a script; the Tika documentation estimates them at roughly 1.6 times the time of eng per page.

Tesseract finds the directory through its compiled-in default or the TESSDATA_PREFIX environment variable. Tika sets TESSDATA_PREFIX for the child process when you configure tessdataPath, or tesseractPath followed by tessdata when only tesseractPath is set (read in the 4.1.0 setEnv method). Use those options instead of a global variable when several Tesseract installations coexist.

Source: Tesseract documentation, Traineddata Files and Apache Tika 4.1.x, TesseractOCRParser Configuration.

TesseractOCRParser probes the binary once, in initialize(). When the probe fails, the parser advertises no media types and does nothing, so a missing install is easy to miss. This check runs the probe:

Output on the test machine, which has no Tesseract:

With Tesseract installed the set lists image/png, image/jpeg, image/tiff, image/bmp, image/gif, image/jp2, image/jpx and image/x-portable-pixmap (the SUPPORTED_TYPES constant of the 4.1.0 source).

Source: TesseractOCRParser, Javadoc 4.1.0.

The official images come in two flavours. apache/tika:<version> holds a JRE and tika-server with every pure-Java parser. apache/tika:<version>-full adds the external tools some parsers shell out to: Tesseract with the eng, ita, fra, spa, deu and jpn language packs, GDAL, ImageMagick (used by the optional Tesseract preprocessing), ffmpeg and font sets. The documentation’s rule of thumb: "Take -full if you OCR scanned documents".

These commands follow the 4.1.x server and Docker pages; they were not run here (no Tika image was available), so no output is shown. With the image running, /rmeta output names the engine in tk:parsed-by for an image, and the PDF reports pdf:ocr-page-count.

The image is built on Ubuntu, runs as UID 35002, and its Dockerfile takes the language list as a build argument (LANGUAGES='eng ita fra spa deu jpn'). To add a language, extend the image:

The Dockerfile on the main branch also sets OMP_THREAD_LIMIT=1, with the comment that parallelism comes from the forked parse workers rather than from Tesseract threads. Check the Dockerfile of the tag you deploy; when you build your own image, set the same variable (see Performance and timeout tuning).

Pin the immutable <version>-<N>-full tags in production, bind to 127.0.0.1 unless you mean to publish the port, and mount a tika-config.json to configure OCR:

Source: Apache Tika 4.1.x, Running Tika in Docker, the -full Dockerfile on GitHub and apache/tika on Docker Hub.

Naming the engine is the safe choice because a broken install fails loudly. This program loads a configuration and parses the Bookshelf files given on the command line:

Run with the engines and text-recognizers configuration above (with "language": "eng") on a machine without Tesseract, it stops at loadAutoDetectParser():

Run with { "text-recognizers": [] } (OCR off) on a generated one-page image-only scanned-loan-form.pdf and a generated book-cover.jpg:

Two details are worth noticing. pdf:ocr-page-count is 1 even with OCR off: it counts the pages that tripped the OCR verdict, whether or not an engine ran, which makes it a good signal for "this PDF needs OCR" in a pipeline that does OCR in a second, slower lane. And the empty text on both files is what an index silently receives when OCR is not configured, which is why a named engine that fails at startup is better than one that is quietly missing.

With Tesseract installed, the same program on the same files is expected to print the recognised text, pdf:ocr-page-count = 1, and TesseractOCRParser among the parser names (for the PDF in tk:parsed-by-full-set, since the engine ran on a page render); that run was not possible here.

Source: Apache Tika 4.1.x, Configuration and Apache Tika 4.1.x, Wiring in Your Own OCR Engine (Verify).

Entries can split the work. Here Tesseract reads TIFF scans and PNG page renders, while JPEG photos (book covers, in this corpus mostly decorative) are skipped, and images smaller than a postage stamp never reach the engine:

The _mime-include and _mime-exclude lists name real types such as image/tiff; the pre-4.1 image/ocr-* spellings are refused at load. The 4.1.x custom-engine page shows the same filters used to keep Tesseract for the formats a second engine does not read.

Source: Apache Tika 4.1.x, Configuration (The text-recognizers list).

Source: Apache Tika 4.1.x, Configuration (Turn OCR off) and TextRecognizerSelection, Javadoc 4.1.0.

The loan forms are typed in English, the reviews are in Spanish and French, and some scans are skewed. This configuration names all three languages, keeps interword spacing for the form fields, turns on ImageMagick preprocessing (available in the -full image) and gives slow scans three minutes:

Every key here appears in the 4.1.x documentation or in the 4.1.0 source; this exact file was not loaded against a running Tesseract. Listing three languages makes Tesseract consider all three models on every image, which costs time (see Performance); when the language of a document is known in advance, set it per request instead.

Source: Apache Tika 4.1.x, TesseractOCRParser Configuration, Apache Tika 4.1.x, Pages and Apache Tika 4.1.x, Timeouts.

The 3.x equivalent, in a labelled block for readers migrating an old tika-config.xml (parameter names from the 3.3.2 source: the parser’s timeout parameter is in seconds and otherTesseractSettings is a list of space-separated pairs):

Source: Apache Tika wiki, TikaOCR (3.x era) and Apache Tika 4.1.x, Migrating to Tika 4.x.

The language option is passed to Tesseract as -l. Guidelines:

pageSegMode is Tesseract’s --psm: how Tesseract splits the image into blocks, lines and words before it recognises them. Tika’s default is 1 (automatic with orientation and script detection), not Tesseract’s own default 3.

Modes 2 (segmentation only, not implemented in recent Tesseract), 5, 8, 9 and 10 (vertical block, single word, word in a circle, single character) are rarely useful for documents. Run tesseract --help-psm for the authoritative list of your build.

With "pageSegMode": "0" Tika runs Tesseract with --psm 0 only (no -l, no -c options), reads the .osd output and records these keys, all defined in the 4.1.0 source: tess:page-number, tess:orientation, tess:rotate, tess:orientation-confidence, tess:script and tess:script-confidence. The tess:rotation and tess:image-magick-processed keys come from the ImageMagick preprocessing path. As with any custom key prefix, see Metadata for how registered prefixes coexist with the tk: namespace.

Source: Tesseract documentation, Improving the quality of the output (Page segmentation method) and the 4.1.0 TesseractOCRParser source.

The Tesseract documentation recommends images of at least 300 dpi and notes that accuracy drops off for text smaller than about 10 points at 300 dpi. Where the resolution comes from depends on the path:

TesseractOCRParser itself passes no --dpi flag (its command line is tesseract <input> <output> --psm <mode> -l <langs> followed by the -c variables and the output type). An image file without resolution metadata makes Tesseract guess; Tesseract’s own user_defined_dpi variable can be set through otherTesseractConfig if you need to fix the assumed resolution. That variable is a Tesseract feature, not a Tika option, and was not tested here.

Source: Apache Tika 4.1.x, Pages (render) and Tesseract documentation, Improving the quality of the output (Rescaling).

Tesseract applies its own binarisation, but skewed, noisy or low-contrast scans improve with preprocessing. Tika’s built-in preprocessing shells out to ImageMagick on a temporary copy of the image:

For heavier cleanup (despeckling, dewarping, border removal) preprocess the images before they reach Tika, or write a custom engine that wraps your pipeline (see Writing a custom OCR engine).

Source: Apache Tika 4.1.x, TesseractOCRParser Configuration and the 4.1.0 TesseractOCRParser, ImagePreprocessor and ImageDeskew sources.

"outputType": "HOCR" makes Tesseract produce hOCR, an HTML dialect with a bounding box for every page, block, line and word. Tika passes the hOCR elements through into its XHTML (the parser’s HOCRPassThroughHandler), so an XHTML handler receives the ocr_line and ocrx_word spans with their title="bbox ..." attributes, while a text or Markdown handler receives only the words. Use it when you need word positions (highlighting search hits on a scan, redaction); keep TXT otherwise. Content handlers are explained in Content Handlers & Output Formats.

TesseractOCRConfig setters reject unsafe or impossible values immediately. This fragment exercises them:

Output (Tika 4.1.0):

The same rules apply to JSON, since the loader binds JSON keys through these setters. The resize check accepts multiples of 100 only, which is why 250 fails although it is inside the range named in the message.

Source: TesseractOCRConfig, Javadoc 4.1.0.

Operators configure the engine once; a request may adjust some of it.

In Java, put a TesseractOCRConfig in the ParseContext. The 4.1.0 parser still reads it when no JSON configuration for tesseract-ocr-parser is in the context ("old-style ParseContext config for backward compatibility" in the source):

This compiles against 4.1.0; it needs Tesseract with the fra model to produce text, and was not run with an engine. A per-request object replaces the whole engine configuration for that parse, so copy the settings you want to keep. The paths, though, are always those of the parser’s initial configuration: the process command line uses the default config’s tesseractPath.

Through JSON (tika-server /tika/config and /rmeta/config endpoints, tika-grpc parse_context_json), the request’s tesseract-ocr-parser block is bound to TesseractOCRConfig.RuntimeConfig. That class refuses tesseractPath, tessdataPath and imageMagickPath (a TikaConfigException), setTrustedPageSeparator, and any otherTesseractConfig, because Tesseract variables such as debug_file name files the binary opens. Operator configuration (the config file and its presets) is trusted and can set all of them.

Source: Apache Tika 4.1.x, TesseractOCRParser Configuration and the 4.1.0 TesseractOCRParser.getConfig and TesseractOCRConfig.RuntimeConfig sources.

Choose Tess4J only when profiling shows that process start-up dominates (many small images, such as page renders or email inline pictures), and run it in forked JVMs with Tika Pipes or tika-server, ideally in a container, so a native crash only kills a fork that is then restarted. Do not load it into a long-lived application server.

Source: Apache Tika 4.1.x, Tess4J OCR Parser (Tess4J vs. TesseractOCRParser).

The Tess4J jar bundles Windows DLLs only. On Linux and macOS install the libraries and point JNA at them:

Set nativeLibPath (prepended to jna.library.path at initialisation), or -Djna.library.path=... on the JVM, to the directory holding the libraries: typically /usr/lib/x86_64-linux-gnu on Debian and Ubuntu, /usr/lib64 on RHEL and Fedora, /opt/homebrew/lib on Apple Silicon and /usr/local/lib on Intel macOS. If JNA cannot find them, the parser advertises no types: named under text-recognizers that fails configuration load with a message naming it.

Source: Apache Tika 4.1.x, Tess4J OCR Parser (Prerequisites, Native library path).

The official page shows the engine inline in the list ("text-recognizers": [{"tess4j-parser": {...}}]); the engines form above is the 4.1 recommended shape and takes the same options. It was not loaded here (no native libraries).

The official Tess4J page itself shows both 2147483647 and 50 MB for maxFileSizeToOcr; the 4.1.0 source has 50 * 1024 * 1024.

Per request in Java, set a Tess4JConfig on the ParseContext:

In caller-supplied JSON, dataPath and nativeLibPath throw TikaConfigException (they point at native code), and poolSize and maxImagePixels throw IllegalStateException: the pool is sized at initialisation, and the pixel guard must not be raised by a caller.

Source: Apache Tika 4.1.x, Tess4J OCR Parser (Configuration options reference, Per-request configuration) and Tess4JConfig, Javadoc 4.1.0.

Adding tika-parser-tess4j-module to the class path is meant to make Tess4J the OCR engine, but when Tesseract is also live and no text-recognizers list exists, the winner depends on registration order, which is not guaranteed. A WARN at startup (since 4.1.0) names the collision and the winner. Name the engine you want in text-recognizers and the question disappears.

The 4.1 pages block is shared by every parser that renders (in 4.1 the PDF parser and the EMF/WMF parsers). Its text value decides where a page’s text comes from:

pages.ocr.maxPages caps the pages of one document that may be OCR’d, counted from the first (-1, the default, for no limit). pages.ocr.auto.totalCharsPerPage (default 10) is the character count below which AUTO OCRs a page, and pages.ocr.auto.unmappedUnicodeCharsPerPage (default 10; a fraction of the page’s characters when below 1) flags pages whose glyphs have no Unicode mapping, a typical sign of a broken font where extraction yields garbage.

The block is read at four layers, later ones winning: parse-context.pages in the config file, pages in a request or preset (which replaces the config’s block entirely), and, overlaid field by field, pages inside the parser’s entry under parsers (for example pdf-parser), and that parser’s pages in a request. The 4.0 spellings still load and land in pages: ocr.strategy (NO_OCR, AUTO, OCR_ONLY, OCR_AND_TEXT_EXTRACTION) became pages.text, ocr.maxPagesToOcr became pages.ocr.maxPages and ocr.dpi became pages.render.dpi. The 3.x PDF parser options were ocrStrategy, ocrStrategyAuto, ocrDPI, ocrImageType and ocrRenderingStrategy (checked in the 3.3.2 PDFParserConfig source).

Source: Apache Tika 4.1.x, Pages: rendering, OCR policy, emitted page images. The PDF side (render engines, renderingStrategy, encrypted and XFA documents) is covered in PDF Parsing.

The policy is a PagesConfig object (org.apache.tika.parser.pages) with a TextPolicy enum. This program forces OCR on scanned-loan-form.pdf, first with no engine, then with the recognizers switched off for the request, and finally loads { "parse-context": { "pages": { "text": "EXTRACT" } } } from a file:

Output on the test machine (no OCR engine installed; message wrapped for the page):

The three lines show the contract: OCR without an engine is an error, not a silent empty result; a request that turns recognizers off is allowed to have none; and EXTRACT does not even evaluate the verdict, so pdf:ocr-page-count is 0. The output was produced by running this program against Tika 4.1.0.

Source: PagesConfig, Javadoc 4.1.0 and Apache Tika 4.1.x, Pages.

A PDF also stores pictures as image objects. With "extractInlineImages": true on pdf-parser, each one is parsed as an embedded document, so image-parser sends it to the OCR engine like any other image. A scanned page is usually one full-page image, so with both page OCR and inline images on, the page is OCR’d twice: once as a render, once as an inline image. The 4.1.x PDF parser page calls this out. For scan corpora, keep extractInlineImages off and rely on page OCR; turn it on only when you need the pictures themselves (and then consider _min-width/_min-height or _mime-exclude to keep small decorations away from the engine).

Source: Apache Tika 4.1.x, PDF Parser (extractInlineImages).

Pictures in a DOCX, an EML attachment or a ZIP entry are embedded documents; each is parsed by image-parser, which calls the engine. The OCR text then appears in the embedded document’s content: a separate record in /rmeta or RecursiveParserWrapper output, or concatenated into the parent’s text by the default embedded-document handling. Set inlineContent: true on tesseract-ocr-parser to make the text of an image embedded as INLINE (tk:embedded-resource-type) also appear where the picture sits in the parent. See Embedded Documents & Recursive Parsing for how embedded output is collected and limited.

Tika 4.x bounds a parse with three independent settings:

Source: Apache Tika 4.1.x, Timeouts (Overview, Configuration) and Apache Tika 4.1.x, Setting Limits.

How to read the outcomes, summarised from the scenarios on the 4.1.x Timeouts page (a ZIP holding a PDF with three images that need OCR, 10-minute task budget, 60-second stall detector, 120-second Tesseract timeout):

Upgrading from 3.x: timeoutSeconds became timeoutMillis (the old name is rejected as an unknown property), TikaTimeoutException is now a checked TikaException (a catch (RuntimeException e) no longer catches it), and progressTimeoutMillis no longer caps a single external call, so operators who raised it to tolerate slow OCR must raise the OCR timeout instead. Values under one second for any of these are warned as a likely seconds-versus- milliseconds mistake.

Source: Apache Tika 4.1.x, Timeouts (Scenario Walkthroughs, Upgrading from Tika 3.x).