Layout Data (Concept)

Layout Data refers to visual information Grooper certain IP Commands collect, such as lines, checkboxes, barcodes, and detected shapes. This data is stored in a "Grooper.Layout.json" file attached to contract Batch Pages. Layout data is used by certain extractors and other features that rely on the presence of that data to function.

Overview

Layout Data is a foundational concept in Grooper, representing the structural and spatial information extracted from document images. It describes the physical arrangement of graphical features on a page, such as lines, barcodes, checkboxes, custom detected shapes. Layout Data enables Grooper to understand not just what content is present, but where and how it appears, supporting computer vision based data extraction and processing scenarios.

⚠

Layout data is nearly always saved at the contract Batch Page level not the folder Batch Folder level.

While it is technically possible for layout data to be saved to Batch Folders, this article assumes layout data is saved at the Batch Page level.

It is also best practice to execute activities that save layout data (Image Processing and Recognize) at the Batch Page level.

What is layout data?

Layout Data is a collection of information that describes the geometric and logical structure of a document page. This includes:

Horizontal and vertical lines - The position and bounds lines such as those found in tables and boundary markers on documents
Barcodes - The location, type and encoded value of barcodes
OMR boxes - The presence and state of checkboxes and boxes
Shapes - The identification of shapes, stamps, or other graphical marks that match examples supplied by a Grooper designer.

Layout Data is typically generated during image processing and recognition activities, and is used by downstream components to anchor extraction, validate results, and drive automation.

Why is layout data important?

Layout Data serves several critical purposes in Grooper:

Anchoring extraction: By knowing where layout markers are located, extractors can target specific regions or dynamically adjust to variable layouts.
Computer vision-based automation: Many separation, classification, and data extraction tasks rely on Layout Data to make decisions based on the presence or absence of visual features.
Diagnostics and review: Layout Data provides visual overlays and context for reviewing extraction results and troubleshooting issues. For example, this assists in Grooper's highlighting capabilities when displaying tabular data collected by a Data Table.

How is layout data collected?

Layout Data is collected through a variety of IP Commands executed as IP Steps in an IP Profile. IP Profiles are most commonly executed during the Image Processing and Recognize activities.

Recognize will execute IP Profiles in one of two ways:
By an IP Profile referenced in an OCR Profile (useful for collecting layout data from scanned and other image-based pages)
By one assigned to its "Alternate IP" property (useful for collecting layout data from digitally native pages).

Layout Data is collected by the following IP Commands:

Line Detection: The Line Detection command identifies horizontal and vertical lines, storing their positions and properties as part of the page's layout.; The Line Removal command also identifies lines and stores layout data. In addition, it will digitally remove them from the image, which can help improve OCR results when applied by an OCR Profile.

Box Detection: The Box Detection command locates checkboxes, boxes, and similar rectangular features, recording their bounds and check states.; The Box Removal command also identifies checkboxes and stores layout data. In addition, it will digitally remove them from the image, which can help improve OCR results when applied by an OCR Profile.

Barcode Detection: The Barcode Detection command finds barcodes, capturing their type, value, orientation, and location.; The Barcode Removal command also identifies barcodes and stores layout data. In addition, it will digitally remove them from the image, which can help improve OCR results when applied by an OCR Profile.

Shape Detection: The Shape Detection command identifies graphical shapes or stamps, such as logos or custom marks, and records their position, name, and confidence. Shape Detection locates shapes similar to examples supplied by a Grooper designer when the command is configured.; The Shape Removal command also identifies shapes and stores layout data. In addition, it will digitally remove them from the image, which can help improve OCR results when applied by an OCR Profile.

How components use layout data

Dynamic zoning: Extraction zones can be anchored to detected shapes, lines, or boxes, allowing for flexible handling of variable layouts.
Contextual extraction: Extractors can filter or validate results based on proximity to specific features (e.g., only extract text near a detected logo).
Table structure inference: Table extractors use Layout Data to determine the boundaries of rows, columns, and cells, even in complex or irregular tables.
Separation and classification: Layout Data enables event-based separation and classification by detecting the presence of visual triggers.
Diagnostics and visualization: Layout Data is used to generate overlays and visual cues in review and troubleshooting tools.

Components that leverage layout data

Many Grooper components utilize Layout Data to perform their functions more accurately and flexibly. Key examples include:

Region-based extractors: Components such as Read Zone, and Detect Signature can use Layout Data to dynamically define extraction zones based on lines (most commonly) or shapes (less common).

Table Extract Methods: Tabular Layout and Grid Layout can use line locations in the Layout Data to better identify rows, columns, and cell boundaries, enabling robust extraction from tables (often with less setup required on the Grooper designers part too).

OMR extractors: Labeled OMR, Ordered OMR, and Zonal OMR use Layout Data to locate and interpret checkboxes and other rectangular mark regions.

Barcode extractors: Find Barcode returns encoded barcode values located in the Layout Data.

Separation Events: Event-Based Separation events like "Shape Detected" and "Barcode Detected" trigger document separation based on the presence of specific shapes or barcodes, as indicated by Layout Data.

Paragraph and region segmentation: Paragraph Marking and its supporting logic use layout data to analyze line structure and segment text into paragraphs. Layout data helps determine paragraph starts, line wrapping, and the presence of horizontal rules or indents by referencing detected lines and their positions. For example, a horizontal line between two text lines may indicate a paragraph break.

Tab detection: Tab Marking leverages layout data to insert tab characters in extracted text where vertical lines or underlines are present. This enables reliable column separation in tabular data and fill-in-the-blank forms. When the 'Vertical Lines' detection option is enabled, the marker queries the layout for vertical lines between adjacent words, inserting a tab if a dividing line is found. When the 'Underline' option is enabled, the marker checks for underlines beneath whitespace gaps using the layout’s underlines, suppressing tab insertion for fill-in regions.

Region snapping: Extractors "Line Snap Options" use layout data to automatically adjust the edges of rectangular regions (such as that of an extraction result on the page) so that they align with nearby lines.

AI Quoting and Alignment: The Layout Objects quoting method serializes layout data—including lines, barcodes, checkboxes, and text regions—into a structured format for use by AI models. This enables advanced workflows such as layout analysis, table extraction, and visual question answering, where the AI requires both content and spatial context.

Where is layout data stored?

Layout Data is stored at the Batch Page level in its Grooper file store location. It is saved in a file named "Grooper.Layout.json".

Each Batch Page maintains its own Layout Data, which is updated as Image Processing and Recognize steps are performed. This data is accessible to extractors, separation events, and other components that need to reference the page's structure.

The Grooper.Layout.json file can be viewed by navigating to the Batch Page in the node tree. Go to the "Advanced" tab and you will see it in the "Files" panel. You can open this file by double clicking it.

Note: The Grooper.Layout.json file will only exist if an IP Profile has been run on the Batch Page (by Image Processing or Recognize) and layout data was collected.

Lines

Lines listed in the Grooper.Layout.json file are broken out into Horizontal Lines and Vertical lines. For each line, X/Y coordinates will be listed for the start and stop points. Each line is a separate object in {} brackets. (X1,Y1) is the start position of the line. (X2, Y2) is the end position of the line.

Below is an example of lines in the Grooper.Layout.json file. This example comes from a small table with four columns and four rows:

  "HorizontalLines": [
    {
      "X1": 1.005,
      "Y1": 1.55,
      "X2": 7.485,
      "Y2": 1.55
    },
    {
      "X1": 1.005,
      "Y1": 1.7225,
      "X2": 7.485,
      "Y2": 1.7225
    },
    {
      "X1": 1.005,
      "Y1": 1.9025,
      "X2": 7.485,
      "Y2": 1.9025
    },
    {
      "X1": 1.005,
      "Y1": 2.08,
      "X2": 7.485,
      "Y2": 2.08
    },
    {
      "X1": 1.005,
      "Y1": 2.255,
      "X2": 7.485,
      "Y2": 2.255
    }
  ],
  "VerticalLines": [
    {
      "X1": 1.005,
      "Y1": 1.55,
      "X2": 1.005,
      "Y2": 2.255
    },
    {
      "X1": 2.62,
      "Y1": 1.55,
      "X2": 2.62,
      "Y2": 2.255
    },
    {
      "X1": 4.2425,
      "Y1": 1.55,
      "X2": 4.2425,
      "Y2": 2.255
    },
    {
      "X1": 5.87,
      "Y1": 1.55,
      "X2": 5.87,
      "Y2": 2.255
    },
    {
      "X1": 7.485,
      "Y1": 1.55,
      "X2": 7.485,
      "Y2": 2.255
    }
  ]

OMR Checkboxes

Each OMR checkbox identified will be stored in the Grooper.Layout.json file with X/Y coordinates for the bounding rectangle and an IsChecked boolean flag.

The "Bounds" are the checkbox's coordinates, expressed as a bounding rectangle. (X1, Y1) is the top left corner of the rectangle. (X2, Y2) is the bottom right corner of the rectangle.
The "IsChecked" flag indicates whether the corresponding OMR checkbox is filled in (checked).

Below is an example of an OMR checkbox in the Grooper.Layout.json file:

  "OmrBoxes": [
    {
      "Bounds": {
        "X1": 1.6467,
        "X2": 1.7567,
        "Y1": 1.3533,
        "Y2": 1.4633
      },
      "IsChecked": false
    }
  ]

Barcodes

Each barcode identified will be stored in the Grooper.Layout.json file with information regarding the barcode type (symbology), X/Y coordinates for the bounding rectangle, confidence score, orientation, and value.

The "Bounds" are the barcodes coordinates, expressed as a bounding rectangle. (X1, Y1) is the top left corner of the rectangle. (X2, Y2) is the bottom right corner of the rectangle.
The "BarcodeType" is an integer which represents a corresponding barcode symbology. As an example, a BarcodeType of 8 indicates that this Barcode uses the Code 128 symbology.
The "Orientation" indicates the read direction of the barcode. As an example, an Orientation of 1 indicates the barcode was read in East orientation.
The "Value" is the decoded value from the barcode.

Below is an example of a barcode in the Grooper.Layout.json file:

  "Barcodes": [
    {
      "Bounds": {
        "X1": 1.37,
        "Y1": 0.18,
        "X2": 2.04,
        "Y2": 0.68
      },
      "BarcodeType": 8,
      "Orientation": 1,
      "Value": "Example Value",
      "Confidence": 1
    }
  ]

Shapes

Each barcode identified will be stored in the Grooper.Layout.json file with information about it's X/Y location and, importantly to how this information is used in Grooper, the shape's name.

The "Bounds" are the shapes coordinates, expressed as a bounding rectangle. (X1, Y1) is the top left corner of the rectangle. (X2, Y2) is the bottom right corner of the rectangle.
The "ShapeName" is the detected shapes name (as given in the Shape Detection/Shape Removal's "Shape Name" property).
The "SampleName" is the name of the image sample used to match the shape (as given in the Shape Detection/Shape Removal's set of "Sample Images")
The "Confidence" is similarity score to the sample image.
The "Scale" is the scale to the sample image. A value of "1" indicates it is the same size as the sample.

Below is an example of a shape in the Grooper.Layout.json file:

  "Shapes": [
    {
      "Bounds": {
        "X1": 0.56,
        "Y1": 0.66,
        "X2": 2.48,
        "Y2": 2.82
      },
      "ShapeName": "Logo",
      "SampleName": "Logo Sample 1",
      "Confidence": 0.8955,
      "Scale": 1
    }
  ]