Multiple ROI#

The Multiple ROI camera feature allows you to define multiple 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.

The Multiple ROI feature is similar to the Stacked ROI feature, which is only available on Basler ace cameras.

Using the Feature#

How It Works#

The Multiple ROI feature allows you to define regions on the sensor array. The maximum number of regions depends on your camera model.

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.

Instead of defining the size and position of the regions individually, you define rows and columns on the sensor array. Then, each intersection of a column and a row creates a region.

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

The pixel information from within Region 11, Region 21, Region 12, and Region 22 is transmitted as a single image.

Configuring the Rows and Columns#

To configure the rows and columns:

1. Make sure the camera is idle, i.e., not capturing images.
2. Make sure the Reverse X and Reverse Y feature is disabled.
   You can re-enable image mirroring after configuring the rows and columns.
3. Configure the columns:
   1. If you want to define a single column:
      1. Set the BslMultipleROIColumnsEnable parameter to false.
      2. Set the OffsetX parameter to the desired horizontal offset of the column. This value is applied to all regions.
      3. Set the Width parameter to the desired width of the column. This value is applied to all regions.
   2. If you want to define multiple columns:
      1. Set the BslMultipleROIColumnsEnable parameter to true.
      2. Set the BslMultipleROIColumnSelector parameter to the desired column, e.g., Column1.
      3. Set the BslMultipleROIColumnOffset parameter to the desired horizontal offset of the column, e.g., 100.
      4. Set the BslMultipleROIColumnSize parameter to the desired width of the column, e.g., 50.
      5. Repeat the above steps for every column you want to configure.
         Note: To avoid undesired side effects, always configure the columns in ascending order, i.e., start with column 1, then configure column 2, and so on.
4. Configure the rows:
   1. If you want to define a single row:
      1. Set the BslMultipleROIRowsEnable parameter to false.
      2. Set the OffsetY parameter to the desired vertical offset of the row. This value is applied to all regions.
      3. Set the Height parameter to the desired height of the row. This value is applied to all regions.
   2. If you want to define multiple rows:
      1. Set the BslMultipleROIRowsEnable parameter to true.
      2. Set the BslMultipleROIRowSelector parameter to the desired row, e.g., Row1.
      3. Set the BslMultipleROIRowOffset parameter to the desired vertical offset of the row, e.g., 100.
      4. Set the BslMultipleROIRowSize parameter to the desired height of the row, e.g., 50.
      5. Repeat the above steps for every row you want to configure.
         Note: To avoid undesired side effects, always configure the rows in ascending order, i.e., start with row 1, then configure row 2, and so on.
5. If needed, re-enable Reverse X and Reverse Y.
   This automatically adapts the positions of the columns and rows to the mirrored image.

Considerations When Using the Multiple ROI Feature#

• There's a sensor-specific minimum width and height for all regions combined, i.e., for the images created by the Multiple ROI feature. During configuration, the camera automatically adjusts the parameter values and ranges to meet the minimum width and height. The last column is always used to reach the minimum total width. Because the increment of the BslMultipleROIColumnSize parameter is also taken into account, the resulting total width may be larger than the minimum.
  Example: The sensor of your camera has a minimum total width of 530 and allows you to configure up to two columns. If you set the width of column 1 to 200, the camera automatically sets the minimum width of column 2 to 330.
  Example 2: Assume you are using the same sensor as in the example above. Also assume the resolution of that sensor is 1920 x 1200. Now, if you'd set the vertical offset of column 0 to 900, there wouldn't be enough space to define a region that meets the minimum width requirement. Therefore, the camera automatically sets the maximum vertical offset for any column to 670 (1200 sensor width minus 530 minimum total region width).
• Because of the above constraints, Basler strongly recommends configuring the columns and rows in ascending order, i.e., start with column 1, then configure column 2, and so on.
• On color cameras, if the pixel format is set to a format that involves debayering (i.e., RGB or YCbCr pixel formats), consider that the camera can only calculate meaningful color information if the region has at least the size of the debayering region (e.g., 3x3 pixels).

• If the BslMultipleROIColumnsEnable parameter is set to true, the following parameters become read-only:

  • OffsetX: The parameter is set to the horizontal offset of column 1.
  • Width: The parameter is set to the total width of all regions, i.e., the width of the images created by the Multiple ROI feature.

• If the BslMultipleROIRowsEnable parameter is set to true, the following parameters become read-only:

  • 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 Multiple ROI feature.

• Other camera features that affect the image size, e.g., Binning or Pixel Beyond, are applied after the Multiple ROI feature. So when configuring the rows and columns, you don't have to take the effects of those features into account.

• The auto function ROI positions and sizes automatically adapt to the output of the Multiple ROI feature. For example, if the width of all regions combined is 500, the maximum value of the AutoFunctionROIWidth parameter will be 500.

Specifics#

Show all camera models

Sample Code#

// ** In this example, we define two regions in horizontal direction
// that will be transmitted as a single image. **
// Enable the ability to configure multiple columns
camera.BslMultipleROIColumnsEnable.SetValue(true);
// Select column 1
camera.BslMultipleROIColumnSelector.SetValue(BslMultipleROIColumnSelector_Column1);
// The first region should have a horizontal offset of 100 and a width of 300 pixels
camera.BslMultipleROIColumnOffset.SetValue(100);
camera.BslMultipleROIColumnSize.SetValue(300);
// Select column 2
camera.BslMultipleROIColumnSelector.SetValue(BslMultipleROIColumnSelector_Column2);
// The second region should have a horizontal offset of 500 and a width of 400 pixels
camera.BslMultipleROIColumnOffset.SetValue(500);
camera.BslMultipleROIColumnSize.SetValue(400);
// We only need one row, so disable the ability to configure multiple rows
camera.BslMultipleROIRowsEnable.SetValue(false);
// Both regions should have a vertical offset of 200 and a height of 500
camera.OffsetY.SetValue(200);
camera.Height.SetValue(500);

INodeMap& nodemap = camera.GetNodeMap();
// ** In this example, we define two regions in horizontal direction
// that will be transmitted as a single image. **
// Enable the ability to configure multiple columns
CBooleanParameter(nodemap, "BslMultipleROIColumnsEnable").SetValue(true);
// Select column 1
CEnumParameter(nodemap, "BslMultipleROIColumnSelector").SetValue("Column1");
// The first region should have a horizontal offset of 100 and a width of 300 pixels
CIntegerParameter(nodemap, "BslMultipleROIColumnOffset").SetValue(100);
CIntegerParameter(nodemap, "BslMultipleROIColumnSize").SetValue(300);
// Select column 2
CEnumParameter(nodemap, "BslMultipleROIColumnSelector").SetValue("Column2");
// The second region should have a horizontal offset of 500 and a width of 400 pixels
CIntegerParameter(nodemap, "BslMultipleROIColumnOffset").SetValue(500);
CIntegerParameter(nodemap, "BslMultipleROIColumnSize").SetValue(400);
// We only need one row, so disable the ability to configure multiple rows
CBooleanParameter(nodemap, "BslMultipleROIRowsEnable").SetValue(false);
// Both regions should have a vertical offset of 200 and a height of 500
CIntegerParameter(nodemap, "OffsetY").SetValue(200);
CIntegerParameter(nodemap, "Height").SetValue(500);

// ** In this example, we define two regions in horizontal direction
// that will be transmitted as a single image. **
// Enable the ability to configure multiple columns
camera.Parameters[PLCamera.BslMultipleROIColumnsEnable].SetValue(true);
// Select column 1
camera.Parameters[PLCamera.BslMultipleROIColumnSelector].SetValue(PLCamera.BslMultipleROIColumnSelector.Column1);
// The first region should have a horizontal offset of 100 and a width of 300 pixels
camera.Parameters[PLCamera.BslMultipleROIColumnOffset].SetValue(100);
camera.Parameters[PLCamera.BslMultipleROIColumnSize].SetValue(300);
// Select column 2
camera.Parameters[PLCamera.BslMultipleROIColumnSelector].SetValue(PLCamera.BslMultipleROIColumnSelector.Column2);
// The second region should have a horizontal offset of 500 and a width of 400 pixels
camera.Parameters[PLCamera.BslMultipleROIColumnOffset].SetValue(500);
camera.Parameters[PLCamera.BslMultipleROIColumnSize].SetValue(400);
// We only need one row, so disable the ability to configure multiple rows
camera.Parameters[PLCamera.BslMultipleROIRowsEnable].SetValue(false);
// Both regions should have a vertical offset of 200 and a height of 500
camera.Parameters[PLCamera.OffsetY].SetValue(200);
camera.Parameters[PLCamera.Height].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 */
/* ** In this example, we define two regions in horizontal direction */
/* that will be transmitted as a single image. ** */
/* Enable the ability to configure multiple columns */
errRes = PylonDeviceSetBooleanFeature(hdev, "BslMultipleROIColumnsEnable", 1);
CHECK(errRes);
/* Select column 1 */
errRes = PylonDeviceFeatureFromString(hdev, "BslMultipleROIColumnSelector", "Column1");
CHECK(errRes);
/* The first region should have a horizontal offset of 100 and a width of 300 pixels */
errRes = PylonDeviceSetIntegerFeature(hdev, "BslMultipleROIColumnOffset", 100);
CHECK(errRes);
errRes = PylonDeviceSetIntegerFeature(hdev, "BslMultipleROIColumnSize", 300);
CHECK(errRes);
/* Select column 2 */
errRes = PylonDeviceFeatureFromString(hdev, "BslMultipleROIColumnSelector", "Column2");
CHECK(errRes);
/* The second region should have a horizontal offset of 500 and a width of 400 pixels */
errRes = PylonDeviceSetIntegerFeature(hdev, "BslMultipleROIColumnOffset", 500);
CHECK(errRes);
errRes = PylonDeviceSetIntegerFeature(hdev, "BslMultipleROIColumnSize", 400);
CHECK(errRes);
/* We only need one row, so disable the ability to configure multiple rows */
errRes = PylonDeviceSetBooleanFeature(hdev, "BslMultipleROIRowsEnable", 0);
CHECK(errRes);
/* Both regions should have a vertical offset of 200 and a height of 500 */
errRes = PylonDeviceSetIntegerFeature(hdev, "OffsetY", 200);
CHECK(errRes);
errRes = PylonDeviceSetIntegerFeature(hdev, "Height", 500);
CHECK(errRes);

# ** In this example, we define two regions in horizontal direction
# that will be transmitted as a single image. **
# Enable the ability to configure multiple columns
camera.BslMultipleROIColumnsEnable.Value = True
# Select column 1
camera.BslMultipleROIColumnSelector.Value = "Column1"
# The first region should have a horizontal offset of 100 and a width of 300 pixels
camera.BslMultipleROIColumnOffset.Value = 100
camera.BslMultipleROIColumnSize.Value = 300
# Select column 2
camera.BslMultipleROIColumnSelector.Value = "Column2"
# The second region should have a horizontal offset of 500 and a width of 400 pixels
camera.BslMultipleROIColumnOffset.Value = 500
camera.BslMultipleROIColumnSize.Value = 400
# We only need one row, so disable the ability to configure multiple rows
camera.BslMultipleROIRowsEnable.Value = False
# Both regions should have a vertical offset of 200 and a height of 500
camera.OffsetY.Value = 200
camera.Height.Value = 500

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