Balance White#

The Balance White camera feature allows you to manually correct color shifts so that white objects appear white in images acquired.

For this purpose, a digital gain correction can be applied per color channel (red, green, blue).

To automatically correct color shifts, use the Balance White Auto feature.

Using the Feature#

Why Perform White Balance Correction#

Images acquired by your camera may have a color cast, i.e., a tint of a particular color. The reason for this is that different sources of light have different color temperatures. Fluorescent lighting adds a bluish cast to images whereas tungsten incandescent light adds a yellowish cast.

The white balance feature allows you to correct these color shifts by adjusting the intensity of the colors red, green, and blue. As a result, white objects appear white in the acquired images.

Prerequisites#

Performing White Balance Correction#

Set the BalanceRatioSelector to one of the available color channels (Red, Green, or Blue).

Adjust the BalanceRatio parameter value for the selected color channel.

  • Balance ratio = 1: The intensity of the color remains unchanged.
  • Balance ratio > 1: The intensity of the color is increased relative to the other two colors.
  • Balance ratio < 1: The intensity of the color is decreased relative to the other two colors. (This is only possible if your camera model supports balance ratio values lower than 1.)

The increase or decrease in intensity is proportional. For example, if the balance ratio for a color is set to 1.2, the intensity of that color is increased by 20 %.

Repeat the above steps for all available color channels.

Info

  • Specifying a balance ratio lower than 1 also decreases the maximum intensity that the color can achieve. Unless you want to correct a strong predominance of one color, specifying a balance ratio of less than 1 is not recommended.
  • Some color enhancement features, e.g., Light Source Preset or Color Transformation, also have an effect on the white balance settings. If necessary, you can manually re-adjust the white balance after having used these features.

Sample Code#

// Set the red intensity to 108.789%
camera.BalanceRatioSelector.SetValue(BalanceRatioSelector_Red);
camera.BalanceRatioAbs.SetValue(1.08789);
// Set the green intensity to 100%
camera.BalanceRatioSelector.SetValue(BalanceRatioSelector_Green);
camera.BalanceRatioAbs.SetValue(1);
// Set the blue intensity to 219.678%
camera.BalanceRatioSelector.SetValue(BalanceRatioSelector_Blue);
camera.BalanceRatioAbs.SetValue(2.19678);
INodeMap& nodemap = camera.GetNodeMap();
// Set the red intensity to 108.789%
CEnumerationPtr(nodemap.GetNode("BalanceRatioSelector"))->FromString("Red");
CFloatPtr(nodemap.GetNode("BalanceRatioAbs"))->SetValue(1.08789);
// Set the green intensity to 100%
CEnumerationPtr(nodemap.GetNode("BalanceRatioSelector"))->FromString("Green");
CIntegerPtr(nodemap.GetNode("BalanceRatioAbs"))->SetValue(1);
// Set the blue intensity to 219.678%
CEnumerationPtr(nodemap.GetNode("BalanceRatioSelector"))->FromString("Blue");
CFloatPtr(nodemap.GetNode("BalanceRatioAbs"))->SetValue(2.19678);
INodeMap& nodemap = camera.GetNodeMap();
// Set the red intensity to 108.789%
CEnumParameter(nodemap, "BalanceRatioSelector").SetValue("Red");
CFloatParameter(nodemap, "BalanceRatioAbs").SetValue(1.08789);
// Set the green intensity to 100%
CEnumParameter(nodemap, "BalanceRatioSelector").SetValue("Green");
CIntegerParameter(nodemap, "BalanceRatioAbs").SetValue(1);
// Set the blue intensity to 219.678%
CEnumParameter(nodemap, "BalanceRatioSelector").SetValue("Blue");
CFloatParameter(nodemap, "BalanceRatioAbs").SetValue(2.19678);
// Set the red intensity to 108.789%
camera.Parameters[PLCamera.BalanceRatioSelector].SetValue(PLCamera.BalanceRatioSelector.Red);
camera.Parameters[PLCamera.BalanceRatioAbs].SetValue(1.08789);
// Set the green intensity to 100%
camera.Parameters[PLCamera.BalanceRatioSelector].SetValue(PLCamera.BalanceRatioSelector.Green);
camera.Parameters[PLCamera.BalanceRatioAbs].SetValue(1);
// Set the blue intensity to 219.678%
camera.Parameters[PLCamera.BalanceRatioSelector].SetValue(PLCamera.BalanceRatioSelector.Blue);
camera.Parameters[PLCamera.BalanceRatioAbs].SetValue(2.19678);
// Set the red intensity to 108.789%
Pylon.DeviceFeatureFromString(hdev, "BalanceRatioSelector", "Red");
Pylon.DeviceSetFloatFeature(hdev, "BalanceRatioAbs", 1.08789);
// Set the green intensity to 100%
Pylon.DeviceFeatureFromString(hdev, "BalanceRatioSelector", "Green");
Pylon.DeviceSetIntegerFeature(hdev, "BalanceRatioAbs", 1);
// Set the blue intensity to 219.678%
Pylon.DeviceFeatureFromString(hdev, "BalanceRatioSelector", "Blue");
Pylon.DeviceSetFloatFeature(hdev, "BalanceRatioAbs", 2.19678);
/* 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 */
/* Set the red intensity to 108.789% */
errRes = PylonDeviceFeatureFromString(hdev, "BalanceRatioSelector", "Red");
CHECK(errRes);
errRes = PylonDeviceSetFloatFeature(hdev, "BalanceRatioAbs", 1.08789);
CHECK(errRes);
/* Set the green intensity to 100% */
errRes = PylonDeviceFeatureFromString(hdev, "BalanceRatioSelector", "Green");
CHECK(errRes);
errRes = PylonDeviceSetIntegerFeature(hdev, "BalanceRatioAbs", 1);
CHECK(errRes);
/* Set the blue intensity to 219.678% */
errRes = PylonDeviceFeatureFromString(hdev, "BalanceRatioSelector", "Blue");
CHECK(errRes);
errRes = PylonDeviceSetFloatFeature(hdev, "BalanceRatioAbs", 2.19678);
CHECK(errRes);

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