Documentation
Table of contents

Design of the TargetROIDef Object

The TargetROIDef object is used to specify one or more recognition tasks to be performed on some regions of interest (ROIs) within an image.

{
    "Name" : "TA_1",

    "TaskSettingNameArray": [
        "LR_0",// Name of LabelRecognizerTaskSetting Object
        "BR_0",// Name of BarcodeReaderTaskSetting Object
        "DN_0" // Name of DocumentNormalizerTaskSetting Object
    ], 
    "Location": 
    {
        "ReferenceObjectFilter" :
        {  
            "ReferenceTargetROIDefNameArray": ["TR_0", "TR_1"], 
            "AtomicResultTypeArray" : ["ART_TEXT_LINE","ART_BARCODE","ART_FRAME"], 

            "BarcodeFilteringCondition": {},
            "FrameFilteringCondition": {}, 
            "TextLineFilteringCondition": {},
            "ColourRegionFilteringCondition": {}
        },
        "Offset": {
            "ReferenceObjectOriginIndex": 0, 
            "ReferenceObjectType": "ROT_ATOMIC_OBJECT", 
            "MeasuredByPercentage" : 1,
            "FirstPoint" : [ 0, 0 ],
            "SecondPoint" : [ 100, 0 ],
            "ThirdPoint" : [ 100, 100 ],
            "FourthPoint" : [ 0, 100 ],
        }
    }
}

Example 1 – Parameters of TargetROIDef

Summary of TargetROIDef top-level parameters

Parameter Name Description
Name Represents the name of the TargetROIDef object, which serves as its unique identifier.
TaskSettingNameArray Represents the collection of task setting object names, used to refer to the BarcodeReaderTaskSetting,LabelRecognizerTaskSetting,DocumentNormalizerTaskSetting objects. It is used to define recognition tasks such as reading barcodes, recognizing labels, or detecting document quads.
Location Define the spatial location where the recognition tasks are performed. It consists of ReferenceObjectFilter and Offset parameter.
PauseFlag Indicates that the region results generated by this TargetROIDef will not be used by other TargetROIDef objects that depend on it to calculate the target regions, unless the user explicitly performs an Update operation.
BaseTargetROIDefName Represents the name of another TargetROIDef object. It is used to inherit the parameters defined in its parent TargetROIDef object. If a parameter has already been defined in this object, the parameter with the same name will not be inherited from the parent object.

In simple terms, TargetROIDef can be expressed using the following formula:

TargetROIDef = Recognition Task Definition + Spatial Location Definition

Recognition Tasks

The recognition tasks configured on the TargetROIDef object include barcode recognition, label recognition, document boundary detection, etc. The atomic result of each task type is the smallest output item, which can be a barcode, text line, table cell, detected quadrilateral, etc. CapturedResult represents a set of all captured atomic result items on an image. The following table lists the task types and corresponding atomic result item types.

Task Type Performed By Atomic Result Type
Read Barcodes Dynamsoft Barcode Reader SDK BarcodeResultItem
Recognize Text Lines Dynamsoft Label Recognizer SDK TextResultItem
Detect Document Borders Dynamsoft Document Normalizer SDK DetectedQuadResultItem
Normalize a Document Dynamsoft Document Normalizer SDK NormalizedImageResultItem

If you want to learn more about the design details of recognition task settings, please refer to the following links:

Spatial Location

Parameter Location defines the spatial location where the recognition tasks are performed. It consists of ReferenceObjectFilter parameter and Offset parameter. The former is used to filter out the desired reference regions, and the latter defines a uniform offset relative to the reference regions. Next, we focus on explaining some key concepts based on the example diagram below:

An example showing the key concepts

Figure 1 – An example showing the key concepts

Concept Description Explanation with example
Atomic Result Represents the atomic result of the recognition task output. It can be a color detection region, a barcode, a text line, a table cell, a detected quadrilateral etc. T1, T2, T3 are three atomic result objects of TextLineResultItem type, and B1 is one atomic object of BarcodeResultItem type.
Reference Region A reference region is a physical quadrilateral region. It includes two types: entire image region and atomic result region. The former refers to the quadrilateral extent of the original image, and the latter refers to the quadrilateral extent of each atomic result. ROI1 has only one reference region which is the entire image region. ROI2 has three reference regions which generated from T1, T2, T3.
Target Region A target region is a physical quadrilateral region, which is calculated from a reference region and offset. ROI1 has only one target region, which is equal to the reference region. ROI2 has three target regions, which are calculated by offsets from quadrilateral regions of T1, T2, T3.

Reference Object Filter

Defines the filter conditions of the reference objects. You can filter the reference objects by the TargetROIDefName, the type of the atomic results and even the further details of the atomic results. There might exist multiple objects that fit the filter conditions. As a result, the more appropriate the filter conditions are, the more accurate reference regions you receive.

Summary of ReferenceObjectFilter top-level parameters

Parameter Name Description
ReferenceTargetROIDefNameArray Reference the atomic object generated by other TargetROIDef objects by specifying its name. This parameter will intersect with the AtomicResultTypeArray parameter to determine the final referenced TargetROIDef objects.
AtomicResultTypeArray Set atomic result types that can be used as reference objects. This parameter will intersect with the ReferenceTargetROIDefNameArray parameter to determine the final referenced TargetROIDef objects.
BarcodeFilteringCondition Set barcode conditions that can be used as reference objects.
FrameFilteringCondition Set frame conditions that can be used as reference objects.
TextLineFilteringCondition Set text line conditions that can be used as reference objects
ColourRegionFilteringCondition Set colour region conditions that can be used as reference objects

Offset

Defines the offset of the target region from the reference object. If there is no reference object defined, the origin will be set to the top-left vertex of the original image.

Offset example

Figure 2 – Offset example

Summary of Offset top-level parameters

Parameter Name Description
ReferenceObjectOriginIndex Defines which point of the reference object will be set as the origin of the coordinate system.
ReferenceObjectType Defines which coordinate system to use when configuring offset parameters basd on the reference objects.
ReferenceXAxis Defines the x-axis of the coordinate system to use when configuring offset parameters basd on the reference objects.
ReferenceYAxis Defines the y-axis of the coordinate system to use when configuring offset parameters basd on the reference objects.
MeasuredByPercentage Sets whether or not to use percentage to measure the points’ coordinates.
FirstPoint The first point of the target region, which defines the offset from the origin.
SecondPoint The second point of the target region, which defines the offset from the origin.
ThirdPoint The third point of the target region, which defines the offset from the origin.
FourthPoint The fourth point of the target region, which defines the offset from the origin.

How to Configure Target/Reference Relationships

Reference the Original Image

Even if you don’t have any reference object, you can still set a offset based on the original image to localize the ROI.

The following parameter template snippet shows how to define ROI from the original image and perform barcode recognition.

  • Step 1: Name your TargetROI “ROI_0”.
  • Step 2: Set the ReferenceObjectFilter of the “ROI_0” to null.
  • Step 3: Define the Offset. Here it is assumed that barcode recognition is performed on the upper part(50%) of the image.
{
    "TargetROIDefOptions": 
    [
        {
            "Name": "ROI_0",
            "TaskSettingNameArray":["barcode_task"],
            "Location": 
            {
                "ReferenceObjectFilter": null,
                "Offset":
                {
                    "MeasuredInPercentage": 1,
                    "FirstPoint": [ 0, 0 ],
                    "SecondPoint": [ 100, 0 ],
                    "ThirdPoint": [ 100, 50 ],
                    "FourthPoint": [ 0, 50 ]
                }
            },
        }
    ]
}

Reference Another TargetObjectDef

If the there exists significant objects that can help you localizing the targeting content, you can define filter conditions to localize the reference objects first and then capture the targeting content.

The following example shows how to configure the ReferenceObjectFilter to use the barcode location to extract the certain text line information:

set-reference-object

Figure 3 – How to reference another TargetObjectDef</b>

{
    "TargetROIDefOptions": 
    [
        {
            "Name": "ROI_0",
            "TaskSettingNameArray":["barcode_task"],
            "Location": null
        },        
        {
            "Name": "ROI_1",
            "TaskSettingNameArray":["text_task"],
            "Location": 
            {
                "ReferenceObjectFilter" :
                {  
                    "ReferenceTargetROIDefNameArray": ["ROI_0"], // The ROI that you decoded the barcodes.
                    "AtomicResultTypeArray" : ["ART_BARCODE"], // Set the AtomicResult type to barcode.

                    // Set BarcodeFilteringCondition. Otherwise, all the barcodes will become ReferenceObject.
                    "BarcodeFilteringCondition": 
                    {
                        "BarcodeFormatIds": ["BF_CODE_128"], // Use Code 128 only.
                        "BarcodeTextRegExPattern": "ReferenceObject" // Find the Code 128 whose text has "ReferenceObject"
                    }
                },
                "Offset" :
                {
                    "MeasuredInPercentage" : 1,
                    "FirstPoint" : [ 20, 140 ],
                    "SecondPoint" : [ 60, 140 ],
                    "ThirdPoint" : [ 60, 170 ],
                    "FourthPoint" : [ 20, 170 ]
                }
            },
        }
    ]
}

This page is compatible for:

Version 1.0

Is this page helpful?

YesYes NoNo

In this article:

latest version

  • Latest version
  • Version 2.x
    • Version 2.2.20
    • Version 2.2.10
    • Version 2.2.0
    • Version 2.0.30
    • Version 2.0.20
    • Version 2.0.10
    • Version 2.0.0
Change +
© 2003–2024 Dynamsoft. All rights reserved.
Privacy Statement / Site Map / Home / Purchase / Support