Balance White Auto#
The pixel data for the auto function can come from one or multiple auto function ROIs.
To correct color shifts manually, use the Balance White feature.
Using the Feature#
Enabling or Disabling Balance White Auto#
To enable or disable the Balance White Auto auto function:
- Assign at least one auto function ROI to the Balance White Auto auto function.
Make sure the auto function ROI overlaps the image ROI, either partially or completely. - Set the
BalanceWhiteAuto
parameter to one of the following operating modes:Once
: The camera adjusts the white balance until the average gray values for red, green, and blue are identical. When this has been achieved, or after several calculation cycles, the camera sets the auto function toOff
and applies the balance ratios resulting from the last calculation to all following images.Continuous
: The camera adjusts the white balance continuously while images are being acquired. The adjustment process continues until the operating mode is set toOnce
orOff
.Off
: Disables the Balance White Auto auto function. TheBalanceRatio
parameters remain at the values resulting from the last automatic or manual adjustment.
Info
On the following camera models, the Continuous operating mode is not available: acA1600-20gc, acA1920-25gc, acA2500-14gc, racer 2 S color cameras
How It Works#
Automatic white balancing is a two-step process:
- The camera compares the average gray values of the red, green, and blue pixels. It determines the color with the highest average gray value (i.e., the brightest color) and sets the
BalanceRatio
parameter value for this color to 1. - The camera automatically adjusts the
BalanceRatio
parameter values of the other two colors until the average gray values for red, green, and blue are identical.
As a result, the BalanceRatio
parameter is set to 1 for one color and to a value between 1 and ≈15.98 for the other two colors.
Example: Assume the green pixels in your image have the highest average gray value. If you enable the Balance White Auto auto function, the camera sets the BalanceRatio
parameter value for green to 1. Then, the camera automatically adjusts the BalanceRatio
parameter values for red and blue until the average gray values for red, green, and blue are identical. The new balance ratios could be, e.g., green = 1, red = 1.08789, and blue = 2.19678.
Info
- To view the
BalanceRatio
parameter values for red, green, or blue, switch to the respective color channel using theBalanceRatioSelector
. - When the camera is capturing images continuously, the auto function takes effect with a short delay. The first few images may not be affected by the auto function.
- On boost V color cameras, the auto function ROIs which are assigned to the Balance White Auto auto function, must not contain any color pixels with 100 % saturation. Otherwise, undesirable false-color effects will occur.
Sample Code#
ace Classic/U/L GigE Cameras#
// Select auto function ROI 2
camera.AutoFunctionAOISelector.SetValue(AutoFunctionAOISelector_AOI2);
// Enable the Balance White Auto auto function
// for the auto function ROI selected
camera.AutoFunctionAOIUsageWhiteBalance.SetValue(true);
// Enable Balance White Auto by setting the operating mode to Continuous
camera.BalanceWhiteAuto.SetValue(BalanceWhiteAuto_Continuous);
INodeMap& nodemap = camera.GetNodeMap();
// Select auto function ROI 2
CEnumParameter(nodemap, "AutoFunctionAOISelector").SetValue("AOI2");
// Enable the Balance White Auto auto function
// for the auto function ROI selected
CBooleanParameter(nodemap, "AutoFunctionAOIUsageWhiteBalance").SetValue(true);
// Enable Balance White Auto by setting the operating mode to Continuous
CEnumParameter(nodemap, "BalanceWhiteAuto").SetValue("Continuous");
// Select auto function ROI 2
camera.Parameters[PLCamera.AutoFunctionAOISelector].SetValue(PLCamera.AutoFunctionAOISelector.AOI2);
// Enable the Balance White Auto auto function
// for the auto function ROI selected
camera.Parameters[PLCamera.AutoFunctionAOIUsageWhiteBalance].SetValue(true);
// Enable Balance White Auto by setting the operating mode to Continuous
camera.Parameters[PLCamera.BalanceWhiteAuto].SetValue(PLCamera.BalanceWhiteAuto.Continuous);
/* 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 ROI 2 */
errRes = PylonDeviceFeatureFromString(hdev, "AutoFunctionAOISelector", "AOI2");
CHECK(errRes);
/* Enable the Balance White Auto auto function */
/* for the auto function ROI selected */
errRes = PylonDeviceSetBooleanFeature(hdev, "AutoFunctionAOIUsageWhiteBalance", 1);
CHECK(errRes);
/* Enable Balance White Auto by setting the operating mode to Continuous */
errRes = PylonDeviceFeatureFromString(hdev, "BalanceWhiteAuto", "Continuous");
CHECK(errRes);
# Select auto function ROI 2
camera.AutoFunctionAOISelector.Value = "AOI2"
# Enable the Balance White Auto auto function
# for the auto function ROI selected
camera.AutoFunctionAOIUsageWhiteBalance.Value = True
# Enable Balance White Auto by setting the operating mode to Continuous
camera.BalanceWhiteAuto.Value = "Continuous"
Other Cameras#
// Select auto function ROI 2
camera.AutoFunctionROISelector.SetValue(AutoFunctionROISelector_ROI2);
// Enable the Balance White Auto auto function
// for the auto function ROI selected
camera.AutoFunctionROIUseWhiteBalance.SetValue(true);
// Enable Balance White Auto by setting the operating mode to Continuous
camera.BalanceWhiteAuto.SetValue(BalanceWhiteAuto_Continuous);
INodeMap& nodemap = camera.GetNodeMap();
// Select auto function ROI 2
CEnumParameter(nodemap, "AutoFunctionROISelector").SetValue("ROI2");
// Enable the Balance White Auto auto function
// for the auto function ROI selected
CBooleanParameter(nodemap, "AutoFunctionROIUseWhiteBalance").SetValue(true);
// Enable Balance White Auto by setting the operating mode to Continuous
CEnumParameter(nodemap, "BalanceWhiteAuto").SetValue("Continuous");
// Select auto function ROI 2
camera.Parameters[PLCamera.AutoFunctionROISelector].SetValue(PLCamera.AutoFunctionROISelector.ROI2);
// Enable the Balance White Auto auto function
// for the auto function ROI selected
camera.Parameters[PLCamera.AutoFunctionROIUseWhiteBalance].SetValue(true);
// Enable Balance White Auto by setting the operating mode to Continuous
camera.Parameters[PLCamera.BalanceWhiteAuto].SetValue(PLCamera.BalanceWhiteAuto.Continuous);
/* 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 ROI 2 */
errRes = PylonDeviceFeatureFromString(hdev, "AutoFunctionROISelector", "ROI2");
CHECK(errRes);
/* Enable the Balance White Auto auto function */
/* for the auto function ROI selected */
errRes = PylonDeviceSetBooleanFeature(hdev, "AutoFunctionROIUseWhiteBalance", 1);
CHECK(errRes);
/* Enable Balance White Auto by setting the operating mode to Continuous */
errRes = PylonDeviceFeatureFromString(hdev, "BalanceWhiteAuto", "Continuous");
CHECK(errRes);
# Select auto function ROI 2
camera.AutoFunctionROISelector.Value = "ROI2"
# Enable the Balance White Auto auto function
# for the auto function ROI selected
camera.AutoFunctionROIUseWhiteBalance.Value = True
# Enable Balance White Auto by setting the operating mode to Continuous
camera.BalanceWhiteAuto.Value = "Continuous"
You can also use the pylon Viewer to easily set the parameters.