Skip to content

Dual ROI#

The Dual ROI camera feature allows you to define two regions on the sensor array that will be transmitted as a single image.

Only the pixel data from those regions will be transmitted. This increases the camera's frame rate.

This feature is only available on Basler boost V camera models.

Using the Feature#

How It Works#

The Dual ROI feature allows you to define two regions on the sensor array in vertical direction.

When an image is acquired, only the pixel information from within the regions is read out of the sensor and transmitted as a single image.

  • The height and the vertical offset can be defined individually for both regions. You do so by configuring rows on the sensor array.
  • The width and horizontal offset are always identical for both regions. They are defined by the global OffsetX and Width parameters.

In the example below, two rows have been defined. This creates two regions:

Dual ROI Example

The pixel information from within Region 1 and Region 2 is transmitted as a single image.

Configuring the Regions#

To configure the regions:

  1. Make sure the camera is idle, i.e., not capturing images.
  2. Set the BslDualROIRowsEnable parameter to true.
  3. Set the BslDualROIRowSelector parameter to Row1.
  4. Set the BslDualROIRowOffset parameter to the desired vertical offset of the row, e.g., 100.
  5. Set the BslDualROIRowSize parameter to the desired height of the row, e.g., 50.
  6. Verify that the value of the BslDualROIImageValid parameter is true. If not, change your parameter settings.
    For example, the regions must not overlap, and the total height of all regions must not exceed the height of the image sensor.
  7. Repeat the above steps for row 2.
  8. Set the OffsetX parameter to the desired horizontal offset of both regions.
  9. Set the Width parameter to the desired width of both regions.

Considerations When Using the Dual ROI Feature#

  • If the BslDualROIRowsEnable parameter is set to true, the following parameters are set automatically whenever image acquisition starts:

    • OffsetY: The parameter is set to the vertical offset of row 1.
    • Height: The parameter is set to the total height of all regions, i.e., the height of the images created by the Dual ROI feature.

    Changing these parameters while using the Dual ROI feature is possible, but has no effect.

  • The auto function ROI position and size does not automatically adapt to the output of the Dual ROI feature. If you're using an auto function, make sure the Dual ROI regions are contained in the auto function ROI.

Sample Code#

// ** In this example, we define two regions in vertical direction
// that will be transmitted as a single image. **
// Enable the Dual ROI feature
camera.BslDualROIRowsEnable.SetValue(true);
// Select row 1
camera.BslDualROIRowSelector.SetValue(BslDualROIRowSelector_Row1);
// The first region should have a vertical offset of 100 and a height of 300 pixels
camera.BslDualROIRowOffset.SetValue(100);
camera.BslDualROIRowSize.SetValue(300);
// Select row 2
camera.BslDualROIRowSelector.SetValue(BslDualROIRowSelector_Row1);
// The second region should have a vertical offset of 500 and a height of 400 pixels
camera.BslDualROIRowOffset.SetValue(500);
camera.BslDualROIRowSize.SetValue(400);
// Check whether the outgoing image is valid
bool heightValid = camera.BslDualROIImageValid.GetValue();
// Both regions should have a horizontal offset of 200 and a width of 500
camera.OffsetX.SetValue(200);
camera.Width.SetValue(500);

INodeMap& nodemap = camera.GetNodeMap();
// ** In this example, we define two regions in vertical direction
// that will be transmitted as a single image. **
// Enable the Dual ROI feature
CBooleanParameter(nodemap, "BslDualROIRowsEnable").SetValue(true);
// Select row 1
CEnumParameter(nodemap, "BslDualROIRowSelector").SetValue("Row1");
// The first region should have a vertical offset of 100 and a height of 300 pixels
CIntegerParameter(nodemap, "BslDualROIRowOffset").SetValue(100);
CIntegerParameter(nodemap, "BslDualROIRowSize").SetValue(300);
// Select row 2
CEnumParameter(nodemap, "BslDualROIRowSelector").SetValue("Row1");
// The second region should have a vertical offset of 500 and a height of 400 pixels
CIntegerParameter(nodemap, "BslDualROIRowOffset").SetValue(500);
CIntegerParameter(nodemap, "BslDualROIRowSize").SetValue(400);
// Check whether the outgoing image is valid
bool heightValid = CBooleanParameter(nodemap, "BslDualROIImageValid").GetValue();
// Both regions should have a horizontal offset of 200 and a width of 500
CIntegerParameter(nodemap, "OffsetX").SetValue(200);
CIntegerParameter(nodemap, "Width").SetValue(500);

// ** In this example, we define two regions in vertical direction
// that will be transmitted as a single image. **
// Enable the Dual ROI feature
camera.Parameters[PLCamera.BslDualROIRowsEnable].SetValue(true);
// Select row 1
camera.Parameters[PLCamera.BslDualROIRowSelector].SetValue(PLCamera.BslDualROIRowSelector.Row1);
// The first region should have a vertical offset of 100 and a height of 300 pixels
camera.Parameters[PLCamera.BslDualROIRowOffset].SetValue(100);
camera.Parameters[PLCamera.BslDualROIRowSize].SetValue(300);
// Select row 2
camera.Parameters[PLCamera.BslDualROIRowSelector].SetValue(PLCamera.BslDualROIRowSelector.Row1);
// The second region should have a vertical offset of 500 and a height of 400 pixels
camera.Parameters[PLCamera.BslDualROIRowOffset].SetValue(500);
camera.Parameters[PLCamera.BslDualROIRowSize].SetValue(400);
// Check whether the outgoing image is valid
bool heightValid = camera.Parameters[PLCamera.BslDualROIImageValid].GetValue();
// Both regions should have a horizontal offset of 200 and a width of 500
camera.Parameters[PLCamera.OffsetX].SetValue(200);
camera.Parameters[PLCamera.Width].SetValue(500);

/* Macro to check for errors */
#define CHECK(errc) if (GENAPI_E_OK != errc) printErrorAndExit(errc)
GENAPIC_RESULT errRes = GENAPI_E_OK;  /* Return value of pylon methods */
_Bool heightValid = false;
/* ** In this example, we define two regions in vertical direction */
/* that will be transmitted as a single image. ** */
/* Enable the Dual ROI feature */
errRes = PylonDeviceSetBooleanFeature(hdev, "BslDualROIRowsEnable", 1);
CHECK(errRes);
/* Select row 1 */
errRes = PylonDeviceFeatureFromString(hdev, "BslDualROIRowSelector", "Row1");
CHECK(errRes);
/* The first region should have a vertical offset of 100 and a height of 300 pixels */
errRes = PylonDeviceSetIntegerFeature(hdev, "BslDualROIRowOffset", 100);
CHECK(errRes);
errRes = PylonDeviceSetIntegerFeature(hdev, "BslDualROIRowSize", 300);
CHECK(errRes);
/* Select row 2 */
errRes = PylonDeviceFeatureFromString(hdev, "BslDualROIRowSelector", "Row1");
CHECK(errRes);
/* The second region should have a vertical offset of 500 and a height of 400 pixels */
errRes = PylonDeviceSetIntegerFeature(hdev, "BslDualROIRowOffset", 500);
CHECK(errRes);
errRes = PylonDeviceSetIntegerFeature(hdev, "BslDualROIRowSize", 400);
CHECK(errRes);
/* Check whether the outgoing image is valid */
errRes = PylonDeviceGetBooleanFeature(hdev, "BslDualROIImageValid", &heightValid);
CHECK(errRes);
/* Both regions should have a horizontal offset of 200 and a width of 500 */
errRes = PylonDeviceSetIntegerFeature(hdev, "OffsetX", 200);
CHECK(errRes);
errRes = PylonDeviceSetIntegerFeature(hdev, "Width", 500);
CHECK(errRes);

# ** In this example, we define two regions in vertical direction
# that will be transmitted as a single image. **
# Enable the Dual ROI feature
camera.BslDualROIRowsEnable.Value = True
# Select row 1
camera.BslDualROIRowSelector.Value = "Row1"
# The first region should have a vertical offset of 100 and a height of 300 pixels
camera.BslDualROIRowOffset.Value = 100
camera.BslDualROIRowSize.Value = 300
# Select row 2
camera.BslDualROIRowSelector.Value = "Row1"
# The second region should have a vertical offset of 500 and a height of 400 pixels
camera.BslDualROIRowOffset.Value = 500
camera.BslDualROIRowSize.Value = 400
# Check whether the outgoing image is valid
heightValid = camera.BslDualROIImageValid.Value
# Both regions should have a horizontal offset of 200 and a width of 500
camera.OffsetX.Value = 200
camera.Width.Value = 500

You can also use the pylon Viewer to easily set the parameters.