Skip to content
Zoan Docs

OCR Extract Form Fields

OCR Extract Form Fields

Section titled “OCR Extract Form Fields”

Type: ocr-extract-form  ·  Package: OCR Activities v1.2.5  ·  Output: Dictionary<string, string>

Since: v1.2.0

Extracts text from named rectangular regions of an image. For each field you define the area (box x, y, w, h) where its value is, and the activity runs OCR only on that area. Ideal for fixed-layout forms (always the same template), where each piece of data is always in the same place.

How it works

Section titled “How it works”

For each field of the fields dictionary, it crops the given region from the image, applies preprocessing and OCR, and stores the text (without leading or trailing spaces and line breaks) under that name.

  • Coordinates are image pixels, with the origin at its top-left corner. A region that goes beyond the image is clipped to its edges.
  • Each field is a separate recognition: with many fields, the activity takes proportionally longer.
  • Because coordinates depend on the image size, all images must have the same resolution as the one used to measure the regions (for example, always scanned at 300 DPI).

Required parameters

Section titled “Required parameters”
ParameterTypeDefaultDescription
pathstring—Path to the image file (.png, .jpg, .bmp, .tiff).
fieldsDictionary—Dictionary fieldName → { "x": …, "y": …, "w": …, "h": … } with the region in pixels (integers).

Optional parameters

Section titled “Optional parameters”
ParameterTypeDefaultDescription
languagestring"eng"Text language: Tesseract code (eng, spa, eng+spa) or regional tag (es-CO). See language.
preprocessstring"none"Prior cleanup of each region: none · auto · deskew · binarize. See preprocessing.

Output

Section titled “Output”

Returns a Dictionary<string, string> with one key per field in fields and the text recognized in its region. A field whose region is not an { x, y, w, h } object, or whose area has no readable text, gets "".

Example

Section titled “Example”

Extract data from a form that always has the same layout:

OCR Extract Form Fields
  path     = formPath
  language = "eng"
  fields = {
     "name":     { "x": 120, "y": 80,  "w": 300, "h": 30 },
     "document": { "x": 120, "y": 130, "w": 200, "h": 30 },
     "date":     { "x": 420, "y": 80,  "w": 150, "h": 30 }
  }
  → output: data


Log   message = "Form from " + data["name"] + " (" + data["document"] + ")"

Common errors

Section titled “Common errors”
MessageCause and fix
'fields' is required.fields is missing.
'fields' must be a dictionary mapping field names to region objects { x, y, w, h }.fields is not a { field: region } object.
Field '…' must declare integer x, y, w, h. Got: …That field’s region is missing a key or a value is not numeric. Use exactly x, y, w, h.
File not found.The path does not exist on the robot’s machine.
Tesseract language '…' not found at '…'. Available: [eng, spa].The language code is not installed.
Section titled “Related activities”