OcrConfig

Configuration for Tesseract OCR text extraction from images and image-containing documents.

importerJavadoc: OcrConfig

Notes

Turns images into text: scanned PDFs, photographed pages, screenshots, TIFF archives. OCR runs through Tesseract, which is not bundled — install it on the machine running the crawler, along with the language data for the languages you expect, and OCR activates once tesseractPath points at it.

By default every supported image format is attempted (TIFF, PNG, JPEG, GIF, BMP, and images embedded in documents such as PDF). OCR is slow next to text extraction, so restricting it with contentTypeMatcher and the file-size bounds is usually worth doing on a large crawl.

Most of the remaining settings map straight onto Tika's Tesseract parameters, and leaving them unset means "whatever Tesseract does by default".

Full distribution only

OCR is one of the optional features left out of the Standard distribution. Use the Full ZIP or an official Docker image, and note that Tesseract itself still has to be installed separately.

Examples

OCR is configured on the parser that will use it, under ocr. Here DefaultParser runs OCR on scanned PDFs and TIFFs in English and French, skipping anything outside a sensible size range.

YAML

handlers:
  - handler:
      class: DefaultParser
      ocr:
        tesseractPath: /usr/bin/tesseract
        language: eng+fra
        contentTypeMatcher:
          method: regex
          pattern: application/pdf|image/tiff
        minFileSizeToOcr: 10000
        maxFileSizeToOcr: 50000000
        timeoutSeconds: 120

JSON

{
  "handlers": [
    {
      "handler": {
        "class": "DefaultParser",
        "ocr": {
          "tesseractPath": "/usr/bin/tesseract",
          "language": "eng+fra",
          "contentTypeMatcher": {
            "method": "regex",
            "pattern": "application/pdf|image/tiff"
          },
          "minFileSizeToOcr": 10000,
          "maxFileSizeToOcr": 50000000,
          "timeoutSeconds": 120
        }
      }
    }
  ]
}

XML

<handlers>
  <handler class="DefaultParser">
    <ocr>
      <tesseractPath>/usr/bin/tesseract</tesseractPath>
      <language>eng+fra</language>
      <contentTypeMatcher method="regex" pattern="application/pdf|image/tiff"/>
      <minFileSizeToOcr>10000</minFileSizeToOcr>
      <maxFileSizeToOcr>50000000</maxFileSizeToOcr>
      <timeoutSeconds>120</timeoutSeconds>
    </ocr>
  </handler>
</handlers>

Usage

Full configuration skeleton, with every option and its default

YAML

applyRotation: false
colorSpace: string
contentTypeMatcher:
  ignoreCase: false
  ignoreDiacritic: false
  matchEmpty: false
  method: BASIC
  negateMatches: false
  partial: false
  pattern: string
  replaceAll: false
  trim: false
density: 0
depth: 0
disabled: false
enableImagePreprocessing: false
filter: string
imageMagickPath: string
language: string
maxFileSizeToOcr: 0
minFileSizeToOcr: 0
pageSegMode: string
pageSeparator: string
preserveInterwordSpacing: false
resize: 0
skipOcr: false
tessdataPath: string
tesseractPath: string
timeoutSeconds: 0

JSON

{
  "applyRotation": false,
  "colorSpace": "string",
  "contentTypeMatcher": {
    "ignoreCase": false,
    "ignoreDiacritic": false,
    "matchEmpty": false,
    "method": "BASIC",
    "negateMatches": false,
    "partial": false,
    "pattern": "string",
    "replaceAll": false,
    "trim": false
  },
  "density": 0,
  "depth": 0,
  "disabled": false,
  "enableImagePreprocessing": false,
  "filter": "string",
  "imageMagickPath": "string",
  "language": "string",
  "maxFileSizeToOcr": 0,
  "minFileSizeToOcr": 0,
  "pageSegMode": "string",
  "pageSeparator": "string",
  "preserveInterwordSpacing": false,
  "resize": 0,
  "skipOcr": false,
  "tessdataPath": "string",
  "tesseractPath": "string",
  "timeoutSeconds": 0
}

XML

<ocr>
  <applyRotation>false</applyRotation>
  <colorSpace>string</colorSpace>
  <contentTypeMatcher>
    <ignoreCase>false</ignoreCase>
    <ignoreDiacritic>false</ignoreDiacritic>
    <matchEmpty>false</matchEmpty>
    <method>BASIC</method>
    <negateMatches>false</negateMatches>
    <partial>false</partial>
    <pattern>string</pattern>
    <replaceAll>false</replaceAll>
    <trim>false</trim>
  </contentTypeMatcher>
  <density>0</density>
  <depth>0</depth>
  <disabled>false</disabled>
  <enableImagePreprocessing>false</enableImagePreprocessing>
  <filter>string</filter>
  <imageMagickPath>string</imageMagickPath>
  <language>string</language>
  <maxFileSizeToOcr>0</maxFileSizeToOcr>
  <minFileSizeToOcr>0</minFileSizeToOcr>
  <pageSegMode>string</pageSegMode>
  <pageSeparator>string</pageSeparator>
  <preserveInterwordSpacing>false</preserveInterwordSpacing>
  <resize>0</resize>
  <skipOcr>false</skipOcr>
  <tessdataPath>string</tessdataPath>
  <tesseractPath>string</tesseractPath>
  <timeoutSeconds>0</timeoutSeconds>
</ocr>

Properties

Property	Type	Required	Default
applyRotation	boolean	No	-
colorSpace	string	No	-
contentTypeMatcher	TextMatcher	No	TextMatcher
density	integer	No	-
depth	integer	No	-
disabled	boolean	No	false
enableImagePreprocessing	boolean	No	-
filter	string	No	-
imageMagickPath	string	No	-
language	string	No	-
maxFileSizeToOcr	integer	No	-
minFileSizeToOcr	integer	No	-
pageSegMode	string	No	-
pageSeparator	string	No	-
preserveInterwordSpacing	boolean	No	-
resize	integer	No	-
skipOcr	boolean	No	-
tessdataPath	string	No	-
tesseractPath	string	No	-
timeoutSeconds	integer	No	-

Property Details

applyRotation

Whether to correct the rotation of an image before reading it. Costs a preprocessing pass; pays for itself on scans that are not square to the page.

colorSpace

Colour space applied during image preprocessing, such as gray. Fed to ImageMagick, so imageMagickPath must be set for it to have any effect.

contentTypeMatcher

Restricts OCR to documents whose content type matches — application/pdf, image/tiff, and so on. Leave it unset to attempt OCR on every supported image format.

density

Image resolution in DPI used during preprocessing. Higher values give the engine more to work with on small text, at the cost of time and memory.

depth

Colour depth in bits used during preprocessing.

disabled

Turns OCR off entirely, regardless of the other settings. Default is false.

enableImagePreprocessing

Whether to run images through ImageMagick before OCR, applying colorSpace, density, depth, filter and resize. Requires imageMagickPath.

filter

ImageMagick filter used when resizing during preprocessing, such as triangle.

imageMagickPath

Path to the ImageMagick installation. Required for any of the preprocessing options to apply.

language

Languages Tesseract should expect, as three-letter ISO 639-2 codes joined with + — for example eng+fra. Each one must be installed in your Tesseract language data. Defaults to English.

maxFileSizeToOcr

Largest file, in bytes, that will be sent to OCR. A useful guard against a single enormous scan stalling a crawl.

minFileSizeToOcr

Smallest file, in bytes, that will be sent to OCR. Screens out icons and spacer images that cost a Tesseract invocation and yield nothing.

pageSegMode

Tesseract's page segmentation mode, as its numeric code — how it should assume the page is laid out (a single column, a single line, a single word, and so on).

pageSeparator

Text inserted between pages in the extracted output.

preserveInterwordSpacing

Whether to keep the original spacing between words rather than normalising it.

resize

Resize percentage applied during preprocessing.

skipOcr

Skips OCR for documents that already carry extractable text, so only the image-only ones pay the cost.

tessdataPath

Path to the Tesseract language data directory (tessdata), when it is not where Tesseract expects it.

tesseractPath

Path to the Tesseract executable. OCR stays inactive until this is set.

timeoutSeconds

How long Tesseract may spend on a single document before it is abandoned.