Tonal Range#

The Tonal Range camera feature allows you to manually adjust contrast or correct color shifts.

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

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.

Adjusting the Contrast#

Info

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:

  1. Set the TonalRangeEnable parameter to On.
  2. Set the TonalRangeSelector parameter to Sum.
  3. Set the TonalRangeSourceDark and TonalRangeTargetDark parameters to the dark source and target values.
    If the dark target value is lower than the dark source value, contrast is increased.
  4. Set the TonalRangeSourceBright and TonalRangeTargetBright parameters to the bright source and target values.
    If the bright target value is greater than the bright source value, contrast is increased.

Correcting Color Shifts#

Info

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:

  1. Set the TonalRangeEnable parameter to On.
  2. Set the TonalRangeSelector parameter to Red, Green, or Blue, depending on the color shift you want to correct.
    Example: If your images have a green cast, set the parameter to Green.
  3. Set the TonalRangeSourceDark, TonalRangeTargetDark, TonalRangeSourceBright, and TonalRangeTargetBright parameters to source and target values that align the current histogram with the other histograms.

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

Source and Target Values#

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.

Source and Target Values Illustration

When the source values are mapped to the target values, the entire histogram spreads or stretches accordingly:

Histogram Stretching Animation

Dark/Bright Source and Target Values

As illustrated above, two sets of source and target values must be defined to perform tonal range operations:

  • Dark source and target values, located at the lower end of the histogram.
    You specify these values using the TonalRangeSourceDark and TonalRangeTargetDark parameters.
  • Bright source and target values, located at the upper end of the histogram.
    You specify these values using the TonalRangeSourceBright and TonalRangeTargetBright parameters.

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.

Contrast Adjustment (Mono and Color Cameras)#

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:

Narrow Tonal Range Example

The Tonal Range feature allows you to manually widen the tonal range and thus increase the contrast.

Wide Tonal Range Example

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.

Color Correction (Color Cameras Only)#

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.

RGB Histogram Alignment Animation

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.

Sample Code#

// 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);
INodeMap& nodemap = camera.GetNodeMap();
// Enable tonal range adjustments
CEnumParameter(nodemap, "TonalRangeEnable").SetValue("On");
// Specify that the summed RGB pixel values are used for tonal range adjustments
CEnumParameter(nodemap, "TonalRangeSelector").SetValue("Sum");
// Set the dark source and target values
CIntegerParameter(nodemap, "TonalRangeSourceDark").SetValue(30);
CIntegerParameter(nodemap, "TonalRangeTargetDark").SetValue(0);
// Set the bright source and target values
CIntegerParameter(nodemap, "TonalRangeSourceBright").SetValue(240);
CIntegerParameter(nodemap, "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.