Auto Function ROI

The Auto Function ROI camera feature allows you to specify the part of the sensor array with which you want to control the camera's auto functions.

ROI is short for region of interest (formerly AOI = area of interest).

You can create several auto function ROIs, each occupying different parts of the sensor array.

The settings for the Auto Function ROI feature are independent of the settings for the Image ROI feature.

In this topic Hide

Using the Feature

Changing Position and Size of an Auto Function ROI

By default, all auto function ROIs are set to the same size as the camera's image ROI. You can change their positions and sizes to suit your needs.

To change the position and size of an auto function ROI:

  1. Set the AutoFunctionAOISelectorAutoFunctionROISelector parameter to one of the available auto function ROIs, e.g., AOI1ROI1.
  2. Enter values for the following parameters to specify the position of the auto function ROI selected:
  3. Enter values for the following parameters to specify the size of the auto function ROI selected:

The position of an auto function ROI is specified based on the lines and rows of the sensor array.

Example: Assume that you have selected auto function ROI 1 and specified the following settings:

This creates the following auto function ROI 1:

Auto Function ROI and Image ROI

Only the pixel data from the area of overlap between the auto function ROI and the image ROI will be used by the auto function assigned to it.

Assigning Auto Functions

By default, each auto function ROI is assigned to a specific auto function. For example, the pixel data from auto function ROI 2 is used to control the Balance White Auto auto function.

On some camera models, the default assignments can be changed. To do so:

  1. Set the AutoFunctionAOISelectorAutoFunctionROISelector parameter to one of the available auto function ROIs, e.g., AOI1ROI1.
  2. Assign the desired auto function(s) to the auto function ROI selected:

Exposure Auto and Gain Auto Assignments Work Together

When making auto function ROI assignments, the Gain Auto auto function and the Exposure Auto auto function always work together. They are considered as a single auto function named "Intensity" or "Brightness", depending on your camera model.

This does not imply, however, that Gain Auto and Exposure Auto must always be enabled at the same time.

Guidelines

When you are setting an auto function ROI, you must follow these guidelines:

Guideline Example
AutoFunctionAOIOffsetXAutoFunctionROIOffsetX + AutoFunctionAOIWidthAutoFunctionROIWidth ≤ Width of camera sensor

Camera with a 1920 x 1080 pixel sensor:

AutoFunctionAOIOffsetXAutoFunctionROIOffsetX + AutoFunctionAOIWidthAutoFunctionROIWidth ≤ 1920

AutoFunctionAOIOffsetYAutoFunctionROIOffsetY + AutoFunctionAOIHeightAutoFunctionROIHeight  ≤ Height of camera sensor

Camera with a 1920 x 1080 pixel sensor:

AutoFunctionAOIOffsetYAutoFunctionROIOffsetY + AutoFunctionAOIHeightAutoFunctionROIHeight ≤ 1080

Overlap Between Auto Function ROI and Image ROI

The size and position of an auto function ROI can be identical to the size and position of the image ROI, but this is not a requirement. For an auto function to work, it is sufficient if both ROIs overlap each other partially.

The overlap between auto function ROI and image ROI determines whether and to what extent the auto function will control the related image property. Only the pixel data from the areas of overlap will be used by the auto function to control the image property of the entire image.

Basler strongly recommends completely including the auto function ROI within the image ROI or choosing identical positions and sizes for auto function ROI and image ROI.

Specifics

Camera Model Auto Function ROIs Default Assignments Assignments Can Be Changed
All ace 2 GigE camera models None, Auto Function ROI feature not supported None, Auto Function ROI feature not supported No
All ace 2 USB 3.0 camera models None, Auto Function ROI feature not supported None, Auto Function ROI feature not supported No
All ace GigE camera models except MED models AOI 1

AOI 2

AOI 1: Intensity (Gain Auto + Exposure Auto)

AOI 2: White Balance (Balance White Auto)

Yes
All ace USB 3.0 camera models except MED models ROI 1

ROI 2

ROI 1: Brightness (Gain Auto + Exposure Auto)

ROI 2: White Balance (Balance White Auto)

Yes
All MED ace GigE camera models AOI 1

AOI 2

AOI 1: Intensity (Gain Auto + Exposure Auto)

AOI 2: White Balance (Balance White Auto), Tonal Range (Tonal Range Auto)

Yes
All MED ace USB 3.0 camera models ROI 1

ROI 2

ROI 1: Brightness (Gain Auto + Exposure Auto)

ROI 2: White Balance (Balance White Auto), Tonal Range (Tonal Range Auto)

Yes
All boost CXP-12 camera models None, Auto Function ROI feature not supported None, Auto Function ROI feature not supported No
All dart BCON for LVDS camera models ROI 1

ROI 2

ROI 1: Brightness (Gain Auto + Exposure Auto)

ROI 2: White Balance (Balance White Auto)

No
All dart BCON for MIPI cameras models None, Auto Function ROI feature not supported None, Auto Function ROI feature not supported No
All dart USB 3.0 camera models ROI 1

ROI 2

ROI 1: Brightness (Gain Auto + Exposure Auto)

ROI 2: White Balance (Balance White Auto)

No
All pulse USB 3.0 camera models ROI 1

ROI 2

ROI 1: Brightness (Gain Auto + Exposure Auto)

ROI 2: White Balance (Balance White Auto)

No

Sample Code

// Select auto function AOI 1
camera.AutoFunctionAOISelector.SetValue(AutoFunctionAOISelector_AOI1);
// Specify position and size of the auto function ROI selected
camera.AutoFunctionAOIOffsetX.SetValue(10);
camera.AutoFunctionAOIOffsetY.SetValue(10);
camera.AutoFunctionAOIWidth.SetValue(500);
camera.AutoFunctionAOIHeight.SetValue(400);
// Enable Balance White Auto for the auto function ROI selected
camera.AutoFunctionAOIUsageWhiteBalance.SetValue(true);
// Enable the 'Intensity' auto function (Gain Auto + Exposure Auto) 
// for the auto function ROI selected
// Note: On some camera models, you must use AutoFunctionROIUseIntensity instead
camera.AutoFunctionAOIUsageIntensity.SetValue(true);
// Select auto function ROI 1
camera.AutoFunctionROISelector.SetValue(AutoFunctionROISelector_ROI1);
// Specify position and size of the auto function ROI selected
camera.AutoFunctionROIOffsetX.SetValue(10);
camera.AutoFunctionROIOffsetY.SetValue(10);
camera.AutoFunctionROIWidth.SetValue(500);
camera.AutoFunctionROIHeight.SetValue(400);
// Enable Balance White Auto for the auto function ROI selected
camera.AutoFunctionROIUseWhiteBalance.SetValue(true);
// Enable the 'Brightness' auto function (Gain Auto + Exposure Auto) 
// for the auto function ROI selected
// Note: On some camera models, you must use AutoFunctionROIUseIntensity instead
camera.AutoFunctionROIUseBrightness.SetValue(true);
INodeMap& nodemap = camera.GetNodeMap();
// Select auto function AOI 1
CEnumerationPtr(nodemap.GetNode("AutoFunctionAOISelector"))->FromString("AOI1");
// Specify position and size of the auto function ROI selected
CIntegerPtr(nodemap.GetNode("AutoFunctionAOIOffsetX"))->SetValue(10);
CIntegerPtr(nodemap.GetNode("AutoFunctionAOIOffsetY"))->SetValue(10);
CIntegerPtr(nodemap.GetNode("AutoFunctionAOIWidth"))->SetValue(500);
CIntegerPtr(nodemap.GetNode("AutoFunctionAOIHeight"))->SetValue(400);
// Enable Balance White Auto for the auto function ROI selected
CBooleanPtr(nodemap.GetNode("AutoFunctionAOIUsageWhiteBalance"))->SetValue(true);
// Enable the 'Intensity' auto function (Gain Auto + Exposure Auto)
// for the auto function ROI selected
// Note: On some camera models, you must use AutoFunctionROIUseIntensity instead
CBooleanPtr(nodemap.GetNode("AutoFunctionAOIUsageIntensity"))->SetValue(true);
// Select auto function ROI 1
CEnumerationPtr(nodemap.GetNode("AutoFunctionROISelector"))->FromString("ROI1");
// Specify position and size of the auto function ROI selected
CIntegerPtr(nodemap.GetNode("AutoFunctionROIOffsetX"))->SetValue(10);
CIntegerPtr(nodemap.GetNode("AutoFunctionROIOffsetY"))->SetValue(10);
CIntegerPtr(nodemap.GetNode("AutoFunctionROIWidth"))->SetValue(500);
CIntegerPtr(nodemap.GetNode("AutoFunctionROIHeight"))->SetValue(400);
// Enable Balance White Auto for the auto function ROI selected
CBooleanPtr(nodemap.GetNode("AutoFunctionROIUseWhiteBalance"))->SetValue(true);
// Enable the 'Brightness' auto function (Gain Auto + Exposure Auto)
// for the auto function ROI selected
// Note: On some camera models, you must use AutoFunctionROIUseIntensity instead
CBooleanPtr(nodemap.GetNode("AutoFunctionROIUseBrightness"))->SetValue(true);
// Select auto function AOI 1
camera.Parameters[PLCamera.AutoFunctionAOISelector].SetValue(PLCamera.AutoFunctionAOISelector.AOI1);
// Specify position and size of the auto function ROI selected
camera.Parameters[PLCamera.AutoFunctionAOIOffsetX].SetValue(10);
camera.Parameters[PLCamera.AutoFunctionAOIOffsetY].SetValue(10);
camera.Parameters[PLCamera.AutoFunctionAOIWidth].SetValue(500);
camera.Parameters[PLCamera.AutoFunctionAOIHeight].SetValue(400);
// Enable Balance White Auto for the auto function ROI selected
camera.Parameters[PLCamera.AutoFunctionAOIUsageWhiteBalance].SetValue(true);
// Enable the 'Intensity' auto function (Gain Auto + Exposure Auto)
// for the auto function ROI selected
// Note: On some camera models, you must use AutoFunctionROIUseIntensity instead
camera.Parameters[PLCamera.AutoFunctionAOIUsageIntensity].SetValue(true);
// Select auto function ROI 1
camera.Parameters[PLCamera.AutoFunctionROISelector].SetValue(PLCamera.AutoFunctionROISelector.ROI1);
// Specify position and size of the auto function ROI selected
camera.Parameters[PLCamera.AutoFunctionROIOffsetX].SetValue(10);
camera.Parameters[PLCamera.AutoFunctionROIOffsetY].SetValue(10);
camera.Parameters[PLCamera.AutoFunctionROIWidth].SetValue(500);
camera.Parameters[PLCamera.AutoFunctionROIHeight].SetValue(400);
// Enable Balance White Auto for the auto function ROI selected
camera.Parameters[PLCamera.AutoFunctionROIUseWhiteBalance].SetValue(true);
// Enable the 'Brightness' auto function (Gain Auto + Exposure Auto)
// for the auto function ROI selected
// Note: On some camera models, you must use AutoFunctionROIUseIntensity instead
camera.Parameters[PLCamera.AutoFunctionROIUseBrightness].SetValue(true);
// Select auto function AOI 1
Pylon.DeviceFeatureFromString(hdev, "AutoFunctionAOISelector", "AOI1");
// Specify position and size of the auto function ROI selected
Pylon.DeviceSetIntegerFeature(hdev, "AutoFunctionAOIOffsetX", 10);
Pylon.DeviceSetIntegerFeature(hdev, "AutoFunctionAOIOffsetY", 10);
Pylon.DeviceSetIntegerFeature(hdev, "AutoFunctionAOIWidth", 500);
Pylon.DeviceSetIntegerFeature(hdev, "AutoFunctionAOIHeight", 400);
// Enable Balance White Auto for the auto function ROI selected
Pylon.DeviceSetBooleanFeature(hdev, "AutoFunctionAOIUsageWhiteBalance", true);
// Enable the 'Intensity' auto function (Gain Auto + Exposure Auto)
// for the auto function ROI selected
// Note: On some camera models, you must use AutoFunctionROIUseIntensity instead
Pylon.DeviceSetBooleanFeature(hdev, "AutoFunctionAOIUsageIntensity", true);
// Select auto function ROI 1
Pylon.DeviceFeatureFromString(hdev, "AutoFunctionROISelector", "ROI1");
// Specify position and size of the auto function ROI selected
Pylon.DeviceSetIntegerFeature(hdev, "AutoFunctionROIOffsetX", 10);
Pylon.DeviceSetIntegerFeature(hdev, "AutoFunctionROIOffsetY", 10);
Pylon.DeviceSetIntegerFeature(hdev, "AutoFunctionROIWidth", 500);
Pylon.DeviceSetIntegerFeature(hdev, "AutoFunctionROIHeight", 400);
// Enable Balance White Auto for the auto function ROI selected
Pylon.DeviceSetBooleanFeature(hdev, "AutoFunctionROIUseWhiteBalance", true);
// Enable the 'Brightness' auto function (Gain Auto + Exposure Auto)
// for the auto function ROI selected
// Note: On some camera models, you must use AutoFunctionROIUseIntensity instead
Pylon.DeviceSetBooleanFeature(hdev, "AutoFunctionROIUseBrightness", true);
/* 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 */
/* Select auto function AOI 1 */
errRes = PylonDeviceFeatureFromString(hdev, "AutoFunctionAOISelector", "AOI1");
CHECK(errRes);
/* Specify position and size of the auto function ROI selected */
errRes = PylonDeviceSetIntegerFeature(hdev, "AutoFunctionAOIOffsetX", 10);
CHECK(errRes);
errRes = PylonDeviceSetIntegerFeature(hdev, "AutoFunctionAOIOffsetY", 10);
CHECK(errRes);
errRes = PylonDeviceSetIntegerFeature(hdev, "AutoFunctionAOIWidth", 500);
CHECK(errRes);
errRes = PylonDeviceSetIntegerFeature(hdev, "AutoFunctionAOIHeight", 400);
CHECK(errRes);
/* Enable Balance White Auto for the auto function ROI selected */
errRes = PylonDeviceSetBooleanFeature(hdev, "AutoFunctionAOIUsageWhiteBalance", 1);
CHECK(errRes);
/* Enable the 'Intensity' auto function (Gain Auto + Exposure Auto) */
/* for the auto function ROI selected */
/* Note: On some camera models, you must use AutoFunctionROIUseIntensity instead */
errRes = PylonDeviceSetBooleanFeature(hdev, "AutoFunctionAOIUsageIntensity", 1);
CHECK(errRes);
/* Select auto function ROI 1 */
errRes = PylonDeviceFeatureFromString(hdev, "AutoFunctionROISelector", "ROI1");
CHECK(errRes);
/* Specify position and size of the auto function ROI selected */
errRes = PylonDeviceSetIntegerFeature(hdev, "AutoFunctionROIOffsetX", 10);
CHECK(errRes);
errRes = PylonDeviceSetIntegerFeature(hdev, "AutoFunctionROIOffsetY", 10);
CHECK(errRes);
errRes = PylonDeviceSetIntegerFeature(hdev, "AutoFunctionROIWidth", 500);
CHECK(errRes);
errRes = PylonDeviceSetIntegerFeature(hdev, "AutoFunctionROIHeight", 400);
CHECK(errRes);
/* Enable Balance White Auto for the auto function ROI selected */
errRes = PylonDeviceSetBooleanFeature(hdev, "AutoFunctionROIUseWhiteBalance", 1);
CHECK(errRes);
/* Enable the 'Brightness' auto function (Gain Auto + Exposure Auto) */
/* for the auto function ROI selected */
/* Note: On some camera models, you must use AutoFunctionROIUseIntensity instead */
errRes = PylonDeviceSetBooleanFeature(hdev, "AutoFunctionROIUseBrightness", 1);
CHECK(errRes);

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