This feature is especially useful if you are using your camera on a light microscope.
If you want to adjust contrast or color shifts manually, use the Tonal Range feature.
If you want to adjust the contrast using linear or S-curve functions, use the Brightness and Contrast feature (if available).
You can define multiple Auto Function ROIs which allow you to use pixel data from different parts of your image.
In this topic Hide
The parameters of the auto function are preset to values that deliver good results in most scenarios.
To adjust the contrast or color or both using the default settings:
To adjust the contrast or color or both using custom settings:
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 auto function 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
auto function uses.
The Tonal Range Auto feature is based on the same concept as the Tonal Range feature: the mapping of source values to target values.
What's different is how the camera determines the source and target values:
Once the camera has determined the source and target values, the camera performs contrast and color adjustments exactly as described in the Tonal Range topic.
During automatic tonal range adjustments, the source values are calculated automatically based on threshold values.
You must specify the threshold values using the AutoTonalRangeThresholdDark and AutoTonalRangeThresholdBright parameters. The parameters are expressed as percentages of all pixels in your image.
In this section, it is assumed that the assigned auto function ROI and the image ROI are identical, which is the default setting. If you changed your auto function ROI settings, the percentages refer to the pixels in the areas of overlap between the assigned auto function ROI and the image ROI.
From the percentages, the camera calculates the following:
The area between both thresholds defines your mid-tones, i.e., the pixel values you consider essential for the image.
Example: Assume you set the AutoTonalRangeThresholdDark parameter to 0.3 and the AutoTonalRangeThresholdBright parameter to 0.4. The camera detects that 0.3 % of the pixels in your image have a pixel value lower than or equal to 52, and 0.4 % of the pixels in your image have a pixel value greater than or equal to 204. Therefore, the dark threshold value is 52, and the bright threshold value is 204.
// Enable contrast adjustments only
camera.AutoTonalRangeModeSelector.SetValue(AutoTonalRangeModeSelector_Contrast);
// Specify that both ends of the tonal range are to be adjusted automatically
camera.AutoTonalRangeAdjustmentSelector.SetValue(AutoTonalRangeAdjustmentSelector_BrightAndDark);
// Set the percentage of pixels that is used to calculate the dark threshold
camera.AutoTonalRangeThresholdDark.SetValue(0.3);
// Set the percentage of pixels that is used to calculate the bright threshold
camera.AutoTonalRangeThresholdBright.SetValue(0.4);
// Set the dark target value
camera.AutoTonalRangeTargetDark.SetValue(0);
// Set the bright target value
camera.AutoTonalRangeTargetBright.SetValue(255);
// Enable the Tonal Range Auto auto function
camera.TonalRangeAuto.SetValue(TonalRangeAuto_Once);
INodeMap& nodemap = camera.GetNodeMap();
// Enable contrast adjustments only
CEnumerationPtr(nodemap.GetNode("AutoTonalRangeModeSelector"))->FromString("Contrast");
// Specify that both ends of the tonal range are to be adjusted automatically
CEnumerationPtr(nodemap.GetNode("AutoTonalRangeAdjustmentSelector"))->FromString("BrightAndDark");
// Set the percentage of pixels that is used to calculate the dark threshold
CFloatPtr(nodemap.GetNode("AutoTonalRangeThresholdDark"))->SetValue(0.3);
// Set the percentage of pixels that is used to calculate the bright threshold
CFloatPtr(nodemap.GetNode("AutoTonalRangeThresholdBright"))->SetValue(0.4);
// Set the dark target value
CIntegerPtr(nodemap.GetNode("AutoTonalRangeTargetDark"))->SetValue(0);
// Set the bright target value
CIntegerPtr(nodemap.GetNode("AutoTonalRangeTargetBright"))->SetValue(255);
// Enable the Tonal Range Auto auto function
CEnumerationPtr(nodemap.GetNode("TonalRangeAuto"))->FromString("Once");
// Enable contrast adjustments only
camera.Parameters[PLCamera.AutoTonalRangeModeSelector].SetValue(PLCamera.AutoTonalRangeModeSelector.Contrast);
// Specify that both ends of the tonal range are to be adjusted automatically
camera.Parameters[PLCamera.AutoTonalRangeAdjustmentSelector].SetValue(PLCamera.AutoTonalRangeAdjustmentSelector.BrightAndDark);
// Set the percentage of pixels that is used to calculate the dark threshold
camera.Parameters[PLCamera.AutoTonalRangeThresholdDark].SetValue(0.3);
// Set the percentage of pixels that is used to calculate the bright threshold
camera.Parameters[PLCamera.AutoTonalRangeThresholdBright].SetValue(0.4);
// Set the dark target value
camera.Parameters[PLCamera.AutoTonalRangeTargetDark].SetValue(0);
// Set the bright target value
camera.Parameters[PLCamera.AutoTonalRangeTargetBright].SetValue(255);
// Enable the Tonal Range Auto auto function
camera.Parameters[PLCamera.TonalRangeAuto].SetValue(PLCamera.TonalRangeAuto.Once);
// Enable contrast adjustments only
Pylon.DeviceFeatureFromString(hdev, "AutoTonalRangeModeSelector", "Contrast");
// Specify that both ends of the tonal range are to be adjusted automatically
Pylon.DeviceFeatureFromString(hdev, "AutoTonalRangeAdjustmentSelector", "BrightAndDark");
// Set the percentage of pixels that is used to calculate the dark threshold
Pylon.DeviceSetFloatFeature(hdev, "AutoTonalRangeThresholdDark", 0.3);
// Set the percentage of pixels that is used to calculate the bright threshold
Pylon.DeviceSetFloatFeature(hdev, "AutoTonalRangeThresholdBright", 0.4);
// Set the dark target value
Pylon.DeviceSetIntegerFeature(hdev, "AutoTonalRangeTargetDark", 0);
// Set the bright target value
Pylon.DeviceSetIntegerFeature(hdev, "AutoTonalRangeTargetBright", 255);
// Enable the Tonal Range Auto auto function
Pylon.DeviceFeatureFromString(hdev, "TonalRangeAuto", "Once");
/* 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 contrast adjustments only */
errRes = PylonDeviceFeatureFromString(hdev, "AutoTonalRangeModeSelector", "Contrast");
CHECK(errRes);
/* Specify that both ends of the tonal range are to be adjusted automatically */
errRes = PylonDeviceFeatureFromString(hdev, "AutoTonalRangeAdjustmentSelector", "BrightAndDark");
CHECK(errRes);
/* Set the percentage of pixels that is used to calculate the dark threshold */
errRes = PylonDeviceSetFloatFeature(hdev, "AutoTonalRangeThresholdDark", 0.3);
CHECK(errRes);
/* Set the percentage of pixels that is used to calculate the bright threshold */
errRes = PylonDeviceSetFloatFeature(hdev, "AutoTonalRangeThresholdBright", 0.4);
CHECK(errRes);
/* Set the dark target value */
errRes = PylonDeviceSetIntegerFeature(hdev, "AutoTonalRangeTargetDark", 0);
CHECK(errRes);
/* Set the bright target value */
errRes = PylonDeviceSetIntegerFeature(hdev, "AutoTonalRangeTargetBright", 255);
CHECK(errRes);
/* Enable the Tonal Range Auto auto function */
errRes = PylonDeviceFeatureFromString(hdev, "TonalRangeAuto", "Once");
CHECK(errRes);
You can also use the pylon Viewer to easily set the parameters.