Tonal Range Auto#

The Tonal Range Auto camera feature allows you to adjust contrast or color shifts or both in a single step.

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.

Using the Feature#

Prerequisites#

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

Info

If you want to optimize the image quality, follow this sequence to avoid side effects:

  1. Use the Exposure Time, Black Level, and Gain features for basic image optimization. Make sure the image is not over saturated.
  2. If you are using a color camera, adjust the white balance by using the Light Source Preset, Balance White Auto, or Balance White features.
  3. Use the Tonal Range Auto and Tonal Range features to optimize the contrast or the colors or both.
  • At least one auto function ROI must be assigned to the Tonal Range Auto auto function.
    By default, an auto function ROI is already assigned.
  • The assigned auto function ROI must overlap the image ROI, either partially or completely.
    By default, the auto function ROI and the image ROI are identical and therefore overlap completely.

Using Tonal Range Auto#

Using Tonal Range Auto with Default Settings#

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:

  1. If you are using a color camera:

    1. If you want to adjust contrast and color in a single step, set the AutoTonalRangeModeSelector parameter to ColorAndContrast.
    2. If you only want to adjust the contrast, set the AutoTonalRangeModeSelector parameter to Contrast.
    3. If you only want to correct color shifts, set the AutoTonalRangeModeSelector parameter to Color.

    (If you are using a mono camera, only contrast adjustment is available. The AutoTonalRangeModeSelector parameter is preset to Contrast and can't be changed.)

  2. Set the TonalRangeAuto parameter to Once.
    With the next image acquisition, the camera adjusts contrast or color or both using the default settings. When the adjustment is complete, the camera sets the auto function to Off and applies the adjustment to all subsequent images.

  3. If you want to fine-tune the adjustments, use the Tonal Range feature.

Using Tonal Range Auto with Custom Settings#

To adjust the contrast or color or both using custom settings:

  1. If you are using a color camera:

    1. If you want to adjust contrast and color in a single step, set the AutoTonalRangeModeSelector parameter to ColorAndContrast.
    2. If you only want to adjust the contrast, set the AutoTonalRangeModeSelector parameter to Contrast.
    3. If you only want to correct color shifts, set the AutoTonalRangeModeSelector parameter to Color.

    (If you are using a mono camera, only contrast adjustment is available. The AutoTonalRangeModeSelector parameter is preset to Contrast and can't be changed.)

  2. Set the AutoTonalRangeAdjustmentSelector parameter to one of the following values:

    • BrightAndDark (default): Automatic adjustments are applied to dark and bright parts of your images.
    • Dark: Automatic adjustments are applied to dark parts of your images only.
    • Bright: Automatic adjustments are applied to bright parts of your images only.
  3. Specify the dark threshold value using the AutoTonalRangeThresholdDark parameter.

  4. Specify the bright threshold value using the AutoTonalRangeThresholdBright parameter.
  5. If the AutoTonalRangeModeSelector parameter is set to ColorAndContrast or Contrast:

    1. Set the AutoTonalRangeTargetDark parameter to the dark target value.
    2. Set the AutoTonalRangeTargetBright parameter to the bright target value.
  6. Set the TonalRangeAuto parameter to Once.
    With the next image acquisition, the camera adjusts contrast or color or both using the default settings. When the adjustment is complete, the camera sets the auto function to Off and applies the adjustment to all subsequent simages.

  7. If you want to fine-tune the adjustments, use the Tonal Range feature.

How It Works#

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.

Info

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.

Source and Target Values#

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:

  • The camera determines the dark and bright source values by calculating the threshold values.
  • The camera determines the dark and bright target values as follows:

    • For contrast adjustments, the camera reads the value of the AutoTonalRangeTargetDark and AutoTonalRangeTargetBright parameters.
    • For color adjustments, the camera automatically determines target values that will properly align the RGB histograms.

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.

Threshold Values#

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.

Info

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 dark threshold value, which is the value in the histogram where the specified amount of pixels have a pixel value lower than or equal to the threshold value.
  • The bright threshold value, which is the value in the histogram where the specified amount of pixels have a pixel value greater than or equal to the threshold value.

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.

Dark and Bright Threshold Illustration

Sample Code#

// 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");
INodeMap& nodemap = camera.GetNodeMap();
// Enable contrast adjustments only
CEnumParameter(nodemap, "AutoTonalRangeModeSelector").SetValue("Contrast");
// Specify that both ends of the tonal range are to be adjusted automatically
CEnumParameter(nodemap, "AutoTonalRangeAdjustmentSelector").SetValue("BrightAndDark");
// Set the percentage of pixels that is used to calculate the dark threshold
CFloatParameter(nodemap, "AutoTonalRangeThresholdDark").SetValue(0.3);
// Set the percentage of pixels that is used to calculate the bright threshold
CFloatParameter(nodemap, "AutoTonalRangeThresholdBright").SetValue(0.4);
// Set the dark target value
CIntegerParameter(nodemap, "AutoTonalRangeTargetDark").SetValue(0);
// Set the bright target value
CIntegerParameter(nodemap, "AutoTonalRangeTargetBright").SetValue(255);
// Enable the Tonal Range Auto auto function
CEnumParameter(nodemap, "TonalRangeAuto").SetValue("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.