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#

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. Make sure the camera already produces 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.
   When optimizing the image quality, follow the sequence given below.
2. Assign at least one auto function ROI to the Tonal Range Auto auto function.
   Make sure the auto function ROI overlaps the image ROI, either partially or completely.
3. 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.)
4. 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.
5. 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.
   3. 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.
   4. If you want to fine-tune the adjustments, use the Tonal Range feature.

Image Optimization Sequence#

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

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.

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.

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.

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
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);

/* 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);

# Enable contrast adjustments only
camera.AutoTonalRangeModeSelector.Value = "Contrast"
# Specify that both ends of the tonal range are to be adjusted automatically
camera.AutoTonalRangeAdjustmentSelector.Value = "BrightAndDark"
# Set the percentage of pixels that is used to calculate the dark threshold
camera.AutoTonalRangeThresholdDark.Value = 0.3
# Set the percentage of pixels that is used to calculate the bright threshold
camera.AutoTonalRangeThresholdBright.Value = 0.4
# Set the dark target value
camera.AutoTonalRangeTargetDark.Value = 0
# Set the bright target value
camera.AutoTonalRangeTargetBright.Value = 255
# Enable the Tonal Range Auto auto function
camera.TonalRangeAuto.Value = "Once"

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