To use this feature, you must be familiar with the concept of tonal range and image histograms.
If you want to adjust the tonal range automatically, use the Tonal Range Auto feature.
If you want to adjust the contrast using linear or S-curve functions, use the Brightness and Contrast feature (if available).
In this topic Hide
Your camera must already produce good images, with only issues like low contrast or shifted colors remaining. Tonal range operations should only be performed on images that already have a good image quality.
Basler recommends using the Tonal Range Auto feature first. After that, you may fine-tune the contrast by following the instructions below.
To manually adjust the contrast:
Basler recommends using the Tonal Range Auto feature first. After that, you may fine-tune the color correction by following the instructions below.
To manually correct color shifts:
Tonal range operations are best understood by looking at a graphical representation of the tonal distribution in your images, i.e., an image histogram.
The Basler pylon Viewer provides the Histogram pane, which can be very helpful when performing tonal range operations.
Depending on which other features are enabled on your camera,
the Histogram pane in the pylon Viewer may not
display the data that the Tonal Range feature actually uses.
For example, the Gamma feature is processed after
tonal range operations. As a result, gamma correction is included in the
histograms displayed in the pylon Viewer, but not in the data that the
Tonal Range feature uses.
Both contrast and color adjustments are based on the same concept of mapping source values to target values.
To illustrate this, think of the source values as "anchors" in the histogram, and the target values as the points where the anchors are moved to.
When the source values are mapped to the target values, the entire histogram spreads or stretches accordingly:
Dark/Bright Source and Target Values
As illustrated above, two sets of source and target values must be defined to perform tonal range operations:
All source and target values can range from 0 to the maximum pixel value (e.g., 4095 if a 12-bit pixel format is set). Because the degree of histogram stretching and spreading is limited, the parameter ranges may also be limited.
On all cameras that support the Tonal Range feature, you can use the feature to adjust contrast.
Low contrast images have a narrow tonal range:
The Tonal Range feature allows you to manually widen the tonal range and thus increase the contrast.
Widening the tonal range is done by mapping the dark source value to a lower target value and the bright source value to a higher target value.
The area between both source values defines your mid-tones, i.e., the pixel values you consider essential for the image.
To automate this process, use the Tonal Range Auto feature.
On color cameras that support the Tonal Range feature, you can also use the feature to correct color shifts.
If colors in your images are shifted, the three RGB (red, green, blue) histograms will appear unaligned. For example, if your images have a red cast, the red histogram will be displayed much further to the right than the green and blue histograms (see example below).
The Tonal Range feature allows you to manually align the RGB histograms and thus reduce color shifts.
You can align the RGB histograms by setting the source and target values so that all histograms are stretched and moved to similar starting and end points.
To automate this process, use the Tonal Range Auto feature.
// Enable tonal range adjustments
camera.TonalRangeEnable.SetValue(TonalRangeEnable_On);
// Specify that the summed RGB pixel values are used for tonal range adjustments
camera.TonalRangeSelector.SetValue(TonalRangeSelector_Sum);
// Set the dark source and target values
camera.TonalRangeSourceDark.SetValue(30);
camera.TonalRangeTargetDark.SetValue(0);
// Set the bright source and target values
camera.TonalRangeSourceBright.SetValue(240);
camera.TonalRangeTargetBright.SetValue(255);
INodeMap& nodemap = camera.GetNodeMap();
// Enable tonal range adjustments
CEnumerationPtr(nodemap.GetNode("TonalRangeEnable"))->FromString("On");
// Specify that the summed RGB pixel values are used for tonal range adjustments
CEnumerationPtr(nodemap.GetNode("TonalRangeSelector"))->FromString("Sum");
// Set the dark source and target values
CIntegerPtr(nodemap.GetNode("TonalRangeSourceDark"))->SetValue(30);
CIntegerPtr(nodemap.GetNode("TonalRangeTargetDark"))->SetValue(0);
// Set the bright source and target values
CIntegerPtr(nodemap.GetNode("TonalRangeSourceBright"))->SetValue(240);
CIntegerPtr(nodemap.GetNode("TonalRangeTargetBright"))->SetValue(255);
// Enable tonal range adjustments
camera.Parameters[PLCamera.TonalRangeEnable].SetValue(PLCamera.TonalRangeEnable.On);
// Specify that the summed RGB pixel values are used for tonal range adjustments
camera.Parameters[PLCamera.TonalRangeSelector].SetValue(PLCamera.TonalRangeSelector.Sum);
// Set the dark source and target values
camera.Parameters[PLCamera.TonalRangeSourceDark].SetValue(30);
camera.Parameters[PLCamera.TonalRangeTargetDark].SetValue(0);
// Set the bright source and target values
camera.Parameters[PLCamera.TonalRangeSourceBright].SetValue(240);
camera.Parameters[PLCamera.TonalRangeTargetBright].SetValue(255);
// Enable tonal range adjustments
Pylon.DeviceFeatureFromString(hdev, "TonalRangeEnable", "On");
// Specify that the summed RGB pixel values are used for tonal range adjustments
Pylon.DeviceFeatureFromString(hdev, "TonalRangeSelector", "Sum");
// Set the dark source and target values
Pylon.DeviceSetIntegerFeature(hdev, "TonalRangeSourceDark", 30);
Pylon.DeviceSetIntegerFeature(hdev, "TonalRangeTargetDark", 0);
// Set the bright source and target values
Pylon.DeviceSetIntegerFeature(hdev, "TonalRangeSourceBright", 240);
Pylon.DeviceSetIntegerFeature(hdev, "TonalRangeTargetBright", 255);
/* 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 */
/* Enable tonal range adjustments */
errRes = PylonDeviceFeatureFromString(hdev, "TonalRangeEnable", "On");
CHECK(errRes);
/* Specify that the summed RGB pixel values are used for tonal range adjustments */
errRes = PylonDeviceFeatureFromString(hdev, "TonalRangeSelector", "Sum");
CHECK(errRes);
/* Set the dark source and target values */
errRes = PylonDeviceSetIntegerFeature(hdev, "TonalRangeSourceDark", 30);
CHECK(errRes);
errRes = PylonDeviceSetIntegerFeature(hdev, "TonalRangeTargetDark", 0);
CHECK(errRes);
/* Set the bright source and target values */
errRes = PylonDeviceSetIntegerFeature(hdev, "TonalRangeSourceBright", 240);
CHECK(errRes);
errRes = PylonDeviceSetIntegerFeature(hdev, "TonalRangeTargetBright", 255);
CHECK(errRes);
You can also use the pylon Viewer to easily set the parameters.