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#

Adjusting the Contrast#

To manually adjust the contrast:

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. Set the TonalRangeEnable parameter to On.
3. Set the TonalRangeSelector parameter to Sum.
4. 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.
5. 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#

To manually correct color shifts:

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. Set the TonalRangeEnable parameter to On.
3. 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.
4. Set the TonalRangeSourceDark, TonalRangeTargetDark, TonalRangeSourceBright, and TonalRangeTargetBright parameters to source and target values that align the current histogram with the other histograms.

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#

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:

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

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.

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.

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.

External Links#

• Light & Photography: Exposure and Tonal Range Considerations (Tuts+)
• Image histogram (Wikipedia)

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

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

# Enable tonal range adjustments
camera.TonalRangeEnable.Value = "On"
# Specify that the summed RGB pixel values are used for tonal range adjustments
camera.TonalRangeSelector.Value = "Sum"
# Set the dark source and target values
camera.TonalRangeSourceDark.Value = 30
camera.TonalRangeTargetDark.Value = 0
# Set the bright source and target values
camera.TonalRangeSourceBright.Value = 240
camera.TonalRangeTargetBright.Value = 255

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