# TargetROIDef Parameters

The `TargetROIDef` object specifies one or more recognition tasks to be performed on regions of interest (ROIs) within an image.

## Example JSON

```json
{
    "TargetROIDefOptions": [
        {
            "Name": "roi_a",
            "BaseTargetROIDefName": "",
            "TaskSettingNameArray": ["dbr_task"],
            "PauseFlag": 0,
            "EnableResultsDeduplication": 1,
            "Location": {
                "ReferenceObjectFilter": {
                    "ReferenceTargetROIDefNameArray": ["roi_root"],
                    "ReferenceTaskSettingNameArray": ["dbr_root"],
                    "ReferenceResultType": "RRT_ORIGINAL_IMAGE"
                },
                "Offset": {
                    "MeasuredByPercentage": 1,
                    "FirstPoint": [0, 0],
                    "SecondPoint": [100, 100]
                }
            }
        }
    ]
}
```

## Hierarchical Structure

This tree shows one `TargetROIDef` object inside `TargetROIDefOptions`.

```text
TargetROIDef
├── Name
├── BaseTargetROIDefName
├── TaskSettingNameArray
├── PauseFlag
├── EnableResultsDeduplication
└── Location
  ├── ReferenceObjectFilter
  └── Offset
```

## Top-Level Parameters

| Parameter Name | Description |
|:---------------|:------------|
| [`Name`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/target-roi-def/name.md) | The unique name of the TargetROIDef object. |
| [`BaseTargetROIDefName`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/target-roi-def/base-target-roidef-name.md) | The name of another TargetROIDef to inherit from. |
| [`TaskSettingNameArray`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/target-roi-def/task-setting-name-array.md) | The names of task setting objects to apply. |
| [`PauseFlag`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/target-roi-def/pause-flag.md) | Whether to pause processing at this ROI. |
| [`EnableResultsDeduplication`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/target-roi-def/enable-results-deduplication.md) | Whether to enable deduplication of results. |
| [`Location`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/target-roi-def/location.md) | The location definition of the target ROI. |

## How TargetROIDef Works

`TargetROIDef` combines two parts:

```text
TargetROIDef = Task Binding + Location Definition
```

### Location-Related Quick Links

| Parameter Name | Description |
|:---------------|:------------|
| [`Location`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/target-roi-def/location.md) | Container object that combines reference filtering and offset definition. |
| [`ReferenceObjectFilter`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/target-roi-def/location/reference-object-filter/index.md) | Filters which reference objects are used when computing the ROI location. |
| [`Offset`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/target-roi-def/location/offset/index.md) | Defines the offset from the reference object to the target ROI. |

## Task Binding

`TaskSettingNameArray` binds one or more task settings to the ROI defined by this `TargetROIDef` object. Typical tasks include barcode reading, text-line recognition, and document processing.

Each task produces atomic result items (for example, barcode, text line, or quadrilateral). `CapturedResult` represents the full set of captured atomic results for an image.

| 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 |
| Deskew a Document | Dynamsoft Document Normalizer SDK | DeskewedImageResultItem |
| Enhance an Image | Dynamsoft Document Normalizer SDK | EnhancedImageResultItem |

For more details:
- [Barcode reader task settings](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-reader-task-settings/index.md)
- [Label recognizer task settings](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/label-recognizer-task-settings/index.md)
- [Document normalizer task settings](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/document-normalizer-task-settings/index.md)

## Location Model

`Location` defines where recognition tasks are performed. It includes:

- `ReferenceObjectFilter`: selects reference regions.
- `Offset`: maps those reference regions to final target regions.

This design enables either fixed ROIs (relative to the original image) or dynamic ROIs (relative to detected results).

![An example showing the key concepts](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/target-roi-def/assets/roi-concept.png)

| Concept | Description | Example Explanation |
| :------ | :---------- | :------------------ |
| **Atomic Result** | The smallest output item from a task (for example, barcode, text line, table cell, or detected quadrilateral). | `T1`, `T2`, `T3` are three `TextLineResultItem` objects, and `B1` is one `BarcodeResultItem` object. |
| **Reference Region** | A physical quadrilateral region used as the positioning base. It can come from the entire image or from atomic results. | `ROI1` has one reference region (entire image). `ROI2` has three reference regions generated from `T1`, `T2`, `T3`. |
| **Target Region** | A physical quadrilateral region calculated from a reference region plus offset rules. | `ROI1` has one target region equal to the reference region. `ROI2` has three target regions calculated by offsets from `T1`, `T2`, `T3` quadrilateral regions. |

### ReferenceObjectFilter

Defines filter conditions for reference objects. You can filter reference objects by `TargetROIDefName`, atomic result type, and specific atomic result details. Multiple objects may fit the filter conditions. More precise filter conditions yield more accurate reference regions.

| Parameter Name | Type | Required/Optional | Description |
| -------------- | ---- | ----------------- | ----------- |
| [`ReferenceTargetROIDefNameArray`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/target-roi-def/location/reference-object-filter/reference-object-filter-parameter-details.md#referencetargetroidefnamearray) | String Array | Optional | References atomic objects generated by other `TargetROIDef` objects by name. Intersects with `AtomicResultTypeArray` to determine final referenced objects. |
| [`AtomicResultTypeArray`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/target-roi-def/location/reference-object-filter/reference-object-filter-parameter-details.md#atomicresulttypearray) | String Array | Optional | Atomic result types that can be used as reference objects. Intersects with `ReferenceTargetROIDefNameArray` to determine final referenced objects. |
| [`BarcodeFilteringCondition`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/target-roi-def/location/reference-object-filter/barcode-filtering-condition.md) | Object | Optional | Barcode conditions that can be used as reference objects. |
| [`FrameFilteringCondition`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/target-roi-def/location/reference-object-filter/frame-filtering-condition.md) | Object | Optional | Frame conditions that can be used as reference objects. |
| [`TextLineFilteringCondition`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/target-roi-def/location/reference-object-filter/text-line-filtering-condition.md) | Object | Optional | Text line conditions that can be used as reference objects. |
| [`RegionFilteringCondition`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/target-roi-def/location/reference-object-filter/region-filtering-condition.md) | Object | Optional | Colour region conditions that can be used as reference objects. |

### Offset

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

![Offset example](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/target-roi-def/assets/location-offset.png)

| Parameter Name | Type | Required/Optional | Description |
| -------------- | ---- | ----------------- | ----------- |
| [`ReferenceObjectOriginIndex`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/target-roi-def/location/offset/offset-parameter-details.md#referenceobjectoriginindex) | Integer | Optional | Which point of the reference object will be set as the origin of the coordinate system. |
| [`ReferenceObjectType`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/target-roi-def/location/offset/offset-parameter-details.md#referenceobjecttype) | String | Optional | Which coordinate system to use when configuring offset parameters based on the reference objects. |
| [`ReferenceXAxis`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/target-roi-def/location/offset/reference-x-axis.md) | Object | Optional | The x-axis of the coordinate system to use when configuring offset parameters based on the reference objects. |
| [`ReferenceYAxis`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/target-roi-def/location/offset/reference-y-axis.md) | Object | Optional | The y-axis of the coordinate system to use when configuring offset parameters based on the reference objects. |
| [`MeasuredByPercentage`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/target-roi-def/location/offset/offset-parameter-details.md#measuredbypercentage) | Integer | Optional | Whether to use percentage to measure the points' coordinates (0 or 1). |
| [`FirstPoint`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/target-roi-def/location/offset/offset-parameter-details.md#firstpoint) | Integer Array | Required | The first point of the target region, defining the offset from the origin. |
| [`SecondPoint`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/target-roi-def/location/offset/offset-parameter-details.md#secondpoint) | Integer Array | Required | The second point of the target region, defining the offset from the origin. |
| [`ThirdPoint`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/target-roi-def/location/offset/offset-parameter-details.md#thirdpoint) | Integer Array | Required | The third point of the target region, defining the offset from the origin. |
| [`FourthPoint`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/target-roi-def/location/offset/offset-parameter-details.md#fourthpoint) | Integer Array | Required | The fourth point of the target region, defining the offset from the origin. |

## Usage Examples

### Reference the Original Image

You can set an offset based on the original image to localize the ROI without any reference object.

**Example:** Define ROI from the original image and perform barcode recognition on the upper 50% of the image.

```json
{
    "TargetROIDefOptions": [
        {
            "Name": "ROI_0",
            "TaskSettingNameArray": ["barcode_task"],
            "Location": {
                "ReferenceObjectFilter": null,
                "Offset": {
                    "MeasuredByPercentage": 1,
                    "FirstPoint": [0, 0],
                    "SecondPoint": [100, 0],
                    "ThirdPoint": [100, 50],
                    "FourthPoint": [0, 50]
                }
            }
        }
    ]
}
```

### Reference Another TargetROIDef

If significant objects can help localize the targeting content, define filter conditions to localize reference objects first, then capture the targeting content.

**Example:** Use barcode location to extract text line information.

![How to reference another TargetROIDef](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/target-roi-def/assets/define-location-with-reference-object.png)

```json
{
    "TargetROIDefOptions": [
        {
            "Name": "ROI_0",
            "TaskSettingNameArray": ["barcode_task"],
            "Location": null
        },
        {
            "Name": "ROI_1",
            "TaskSettingNameArray": ["text_task"],
            "Location": {
                "ReferenceObjectFilter": {
                    "ReferenceTargetROIDefNameArray": ["ROI_0"],
                    "AtomicResultTypeArray": ["ART_BARCODE"],
                    "BarcodeFilteringCondition": {
                        "BarcodeFormatIds": ["BF_CODE_128"],
                        "BarcodeTextRegExPattern": "ReferenceObject"
                    }
                },
                "Offset": {
                    "MeasuredByPercentage": 1,
                    "FirstPoint": [20, 140],
                    "SecondPoint": [60, 140],
                    "ThirdPoint": [60, 170],
                    "FourthPoint": [20, 170]
                }
            }
        }
    ]
}
```