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.

Performing White Balance Correction#

To perform white balance correction:

Set the Balance White Auto auto function to Off.
For best results, set the black level to 0 (zero).
Set the BalanceRatioSelector parameter 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.)
- Repeat steps 3 and 4 for all available color channels.

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 %.

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.

External Links#

Sample Code#

ace Classic/U/L GigE Cameras#

C++ (Native)C++ (Generic)C#C (Generic)Python

// 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.0);
// 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%
CEnumParameter(nodemap, "BalanceRatioSelector").SetValue("Red");
CFloatParameter(nodemap, "BalanceRatioAbs").SetValue(1.08789);
// Set the green intensity to 100%
CEnumParameter(nodemap, "BalanceRatioSelector").SetValue("Green");
CFloatParameter(nodemap, "BalanceRatioAbs").SetValue(1.0);
// 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.0);
// Set the blue intensity to 219.678%
camera.Parameters[PLCamera.BalanceRatioSelector].SetValue(PLCamera.BalanceRatioSelector.Blue);
camera.Parameters[PLCamera.BalanceRatioAbs].SetValue(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 = PylonDeviceSetFloatFeature(hdev, "BalanceRatioAbs", 1.0);
CHECK(errRes);
/* Set the blue intensity to 219.678% */
errRes = PylonDeviceFeatureFromString(hdev, "BalanceRatioSelector", "Blue");
CHECK(errRes);
errRes = PylonDeviceSetFloatFeature(hdev, "BalanceRatioAbs", 2.19678);
CHECK(errRes);

# Set the red intensity to 108.789%
camera.BalanceRatioSelector.Value = "Red"
camera.BalanceRatioAbs.Value = 1.08789
# Set the green intensity to 100%
camera.BalanceRatioSelector.Value = "Green"
camera.BalanceRatioAbs.Value = 1.0
# Set the blue intensity to 219.678%
camera.BalanceRatioSelector.Value = "Blue"
camera.BalanceRatioAbs.Value = 2.19678

Other Cameras#

C++ (Native)C++ (Generic)C#C (Generic)Python

// Set the red intensity to 108.789%
camera.BalanceRatioSelector.SetValue(BalanceRatioSelector_Red);
camera.BalanceRatio.SetValue(1.08789);
// Set the green intensity to 100%
camera.BalanceRatioSelector.SetValue(BalanceRatioSelector_Green);
camera.BalanceRatio.SetValue(1.0);
// Set the blue intensity to 219.678%
camera.BalanceRatioSelector.SetValue(BalanceRatioSelector_Blue);
camera.BalanceRatio.SetValue(2.19678);

INodeMap& nodemap = camera.GetNodeMap();
// Set the red intensity to 108.789%
CEnumParameter(nodemap, "BalanceRatioSelector").SetValue("Red");
CFloatParameter(nodemap, "BalanceRatio").SetValue(1.08789);
// Set the green intensity to 100%
CEnumParameter(nodemap, "BalanceRatioSelector").SetValue("Green");
CFloatParameter(nodemap, "BalanceRatio").SetValue(1.0);
// Set the blue intensity to 219.678%
CEnumParameter(nodemap, "BalanceRatioSelector").SetValue("Blue");
CFloatParameter(nodemap, "BalanceRatio").SetValue(2.19678);

// Set the red intensity to 108.789%
camera.Parameters[PLCamera.BalanceRatioSelector].SetValue(PLCamera.BalanceRatioSelector.Red);
camera.Parameters[PLCamera.BalanceRatio].SetValue(1.08789);
// Set the green intensity to 100%
camera.Parameters[PLCamera.BalanceRatioSelector].SetValue(PLCamera.BalanceRatioSelector.Green);
camera.Parameters[PLCamera.BalanceRatio].SetValue(1.0);
// Set the blue intensity to 219.678%
camera.Parameters[PLCamera.BalanceRatioSelector].SetValue(PLCamera.BalanceRatioSelector.Blue);
camera.Parameters[PLCamera.BalanceRatio].SetValue(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, "BalanceRatio", 1.08789);
CHECK(errRes);
/* Set the green intensity to 100% */
errRes = PylonDeviceFeatureFromString(hdev, "BalanceRatioSelector", "Green");
CHECK(errRes);
errRes = PylonDeviceSetFloatFeature(hdev, "BalanceRatio", 1.0);
CHECK(errRes);
/* Set the blue intensity to 219.678% */
errRes = PylonDeviceFeatureFromString(hdev, "BalanceRatioSelector", "Blue");
CHECK(errRes);
errRes = PylonDeviceSetFloatFeature(hdev, "BalanceRatio", 2.19678);
CHECK(errRes);

# Set the red intensity to 108.789%
camera.BalanceRatioSelector.Value = "Red"
camera.BalanceRatio.Value = 1.08789
# Set the green intensity to 100%
camera.BalanceRatioSelector.Value = "Green"
camera.BalanceRatio.Value = 1.0
# Set the blue intensity to 219.678%
camera.BalanceRatioSelector.Value = "Blue"
camera.BalanceRatio.Value = 2.19678

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