Operator DynamicROI

Operator Library: Base

The operator DynamicROI extracts a rectangular region of interest (ROI) from the input link I. The output image height and line width are defined by the ROI image parameters Ylength and Xlength. The size of this ROI is defined dynamically by the four input links Xoffset, Yoffset, Xlength, and Ylength. The purpose of the operator is to adapt the ROI dimension and location to results of image processing steps. All parameters of the ROI may vary from image to image.

The image stream from I to O is controlled by the four links Xoffset, Yoffset, Xlength, and Ylength. These four links can work fully asynchronous (sourced by different M type operators) as well as fully synchronous (sourced by the same M type operator through an arbitrary network of O type operators). To output an ROI at output O it is required to provide an image at all five inputs. Those inputs where an image is already provided are blocked until at all inputs an image is provided. Buffering elements at the indivdual inputs, especially at input link I, are highly recommended. You can imagine the behavior of DynamicROI as a valve which only opens if an image is provided at all inputs.

Whenever an image arrives at each of the four control inputs the very last pixel of each control link is captured by the DynamicROI. As soon as DynamicROI received all images at the control inputs, the valve opens and an image is allowed to pass from I to O. Now the captured ROI coordinates are used to extract the ROI. After the ROI image has been transferred to O, the valve closes again and waits for the next image ROI coordinate set appearing at the control links.

An important use of this operator is in conjunction with CreateBlankImage and CoefficientBuffer or with the results of an object detection implementation. An operator to control the ROI coordinates using parameter is SelectROI.

Operator Restrictions

  • If the Xlength is not an integer multiple of the parallelism of links I and O, the operator will extend the ROI width to match with the parallelism. Dummy pixels are added to the end of each line. The value of that dummy pixel is undefined. In VA simulation dummy pixels will be set to zero for better visibility.
  • If the ROI coordinates are illegal, i.e. the Xlength and/or Ylength are zero or the offsets exceed the image boundaries, the operator will cut and output an empty image or will remove the image. The behavior can be controlled using parameter SuppressEmptyRoI.
  • If the offset coordinates are valid but the Xlength and/or Ylength coordinates exceed the image boundaries, the operator will shrink ROI to the image boundaries.
  • When an empty coordinate set is provided on ROI inputs, i.e. a ROI frame of height and width equal to 0, operator DynamicROI treats such an empty ROI as a ROI with invalid coordinates. The operator will cut and output an empty image or will remove the image. The behavior can be controlled using parameter SuppressEmptyRoI.
  • Empty images on port I are not supported.
  • The lines of each input image at port I must have the same length. Thus images with varying line lengths are not allowed.

I/O Properties

Property Value
Operator Type M
Input Links I, image input
Xoffset, x-offset input
Yoffset, y-offset input
Xlength, x-length input
Ylength, y-length input
Output Link O, data output

Synchronous and Asynchronous Inputs

  • All inputs are asynchronous, i.e. they may be sourced by different M-type operators.

Supported Link Format

Link Parameter Input Link I Input Link Xoffset Input Link Yoffset Input Link Xlength Input Link Ylength Output Link O
Bit Width [1, 64]1 auto2 auto3 auto4 auto5 as I
Arithmetic {unsigned, signed} unsigned unsigned unsigned unsigned as I
Parallelism any any any any any as I
Kernel Columns any any any any any as I
Kernel Rows any any any any any as I
Max. Img Width any any any any any as I
Max. Img Height any any any any any as I


The range of the input bit width is [1, 64]. For signed inputs, the range is [2, 64]. For unsigned color inputs, the range is [3, 63] and for signed color, the range is [6, 63].

2 3 4 5

The allowed bit width at the control inputs is automatically determined from the maximum image dimensions of the input link I


Type static parameter
Default ON
Range {ON, OFF}

This parameter controls the removal of empty images on the operator's output if the ROI coordinates are illegal. See Operator Restrictions for more information.

Examples of Use

The use of operator DynamicROI is shown in the following examples:

  • 'Blob2D ROI Selection'

    Examples - The blob analysis operator is applied to an input camera image. The applet shows the usage of the blob data in the applet. In this case, the object with the maximum are is localized and the coordinates are used to cut out the object from the original image.