Tonal Range Auto#

相机的 Tonal Range Auto 功能使您可以一步调整对比度和/或色彩偏移。

如果您在光学显微镜上使用相机，则此功能特别有用。

如果要手动调整对比度或色彩偏移，请使用 Tonal Range 功能。

如果要使用线性或 S 曲线函数调整对比度，请使用 Brightness and Contrast 功能（如果可用）。

您可以定义多个 Auto Function ROI，这些 ROI 允许您使用图像不同部分的像素数据。

该功能的使用#

使用 Tonal Range Auto#

使用 Tonal Range Auto 的默认设置#

自动功能的参数预设为在大多数情况下都能产生良好结果的值。

要使用默认设置调整对比度和/或颜色，请执行以下操作：

确保相机已生成出色的图像，并且仅存在对比度低或色彩偏移等问题。色调范围操作只能在已经具有良好图像质量的图像上执行。
优化图像质量时，请按照以下提供的顺序操作。
将至少一个自动功能 ROI 分配给 Tonal Range Auto 自动功能。
确保自动功能 ROI 部分或完全与图像 ROI 重叠。
如果您使用的是彩色相机：
1. 如果您想在一步中同时调整对比度和颜色，请将 AutoTonalRangeModeSelector acquisition mode ColorAndContrast.
2. 如果您只想调整对比度，请将 AutoTonalRangeModeSelector acquisition mode Contrast.
3. 如果您只想校正偏色，请将 AutoTonalRangeModeSelector acquisition mode Color.
  （如果您使用的是黑白相机，则只能调整对比度。 AutoTonalRangeModeSelector 参数预设为 Contrast 且无法更改。）
设置 TonalRangeAuto acquisition mode Once.
在下一次图像采集时，相机将使用默认设置调整对比度、颜色或两者。调整完成后，相机将把自动功能设置为 Off 并将调整应用于所有后续图像。
如果您想进行微调，请使用 Tonal Range 功能。

使用 Tonal Range Auto 的自定义设置#

要使用自定义设置调整对比度和/或颜色，请执行以下操作：

如果您使用的是彩色相机：
1. 如果您想在一步中同时调整对比度和颜色，请将 AutoTonalRangeModeSelector acquisition mode ColorAndContrast.
2. 如果您只想调整对比度，请将 AutoTonalRangeModeSelector acquisition mode Contrast.
3. 如果您只想校正偏色，请将 AutoTonalRangeModeSelector acquisition mode Color.
  （如果您使用的是黑白相机，则只能调整对比度。 AutoTonalRangeModeSelector 参数预设为 Contrast 且无法更改。）
设置 AutoTonalRangeAdjustmentSelector 参数设置为以下值：
- BrightAndDark （默认）：自动调整将应用于图像的暗部和亮部。
- Dark：自动调整仅应用于图像的暗部。
- Bright：自动调整仅应用于图像的亮部。
指定暗部阈值使用的工具为 AutoTonalRangeThresholdDark 参数。
指定亮部阈值使用的工具为 AutoTonalRangeThresholdBright 参数。
如果 AutoTonalRangeModeSelector 参数设置为 ColorAndContrast 或 Contrast:
1. 设置 AutoTonalRangeTargetDark 参数设为暗部目标值.
2. 设置 AutoTonalRangeTargetBright 参数设为亮部目标值.
3. 设置 TonalRangeAuto acquisition mode Once.
  在下一次图像采集时，相机将使用默认设置调整对比度、颜色或两者。调整完成后，相机将把自动功能设置为 Off 并将调整应用于所有后续图像。
4. 如果您想进行微调，请使用 Tonal Range 功能。

图像优化顺序#

如果要优化图像质量，请按照以下顺序操作，以避免产生副作用：

使用 Exposure Time、Black Level 和 Gain 功能执行基本图像优化。确保图像不会过度饱和。
如果您使用的是彩色相机，请使用 Light Source Preset、Balance White Auto 或 Balance White 功能。
使用 Tonal Range Auto 和 Tonal Range 功能优化对比度和/或颜色。

运作原理#

通过查看图像中色调分布的图形化表示（即图像直方图），可以更好地理解色调范围操作。

Basler pylon Viewer 提供了直方图窗格，这在执行色调范围操作时会非常有用。

信息

根据相机上启用的其他功能，pylon Viewer 中的直方图窗格可能不会显示自动功能实际使用的数据。
例如，Gamma 功能是在色调范围操作后处理的。因此，Gamma 校正包含在 pylon Viewer 中显示的直方图中，但不包含在自动功能使用的数据中。

源和目标值#

Tonal Range Auto 功能基于与 Tonal Range 功能相同的概念：源值到目标值的映射。

区别在于相机确定源值和目标值的方式：

相机通过计算阈值确定暗/亮源值。
相机如下确定暗/亮目标值：
- 对于对比度调整，相机将读取 AutoTonalRangeTargetDark 和 AutoTonalRangeTargetBright 参数。
- 对于色彩调节，相机会自动确定将正确对齐 RGB 直方图的目标值。

相机确定了源值和目标值后，将完全按照“Tonal Range”主题中的说明执行对比度和色彩调节。

阈值#

在自动调节色调范围时，将根据阈值自动计算源值。

您必须使用以下参数指定阈值 AutoTonalRangeThresholdDark 和 AutoTonalRangeThresholdBright 参数。这些参数以图像中所有像素的百分比表示。

信息

在本节中，假定分配的自动功能 ROI 和图像 ROI 相同，这是默认设置。如果您更改了自动功能 ROI 设置，则百分比是指分配的自动功能 ROI 与图像 ROI 间重叠区域中的像素。

相机根据这些百分比计算出以下内容：

暗阈值是直方图中指定数量像素的像素值小于或等于阈值的值。
亮阈值，是直方图中指定数量像素的像素值大于或等于阈值的值。

两个阈值之间的区域定义了中间色调，即您认为对图像至关重要的像素值。

示例： 假设您将 AutoTonalRangeThresholdDark 参数设为 0.3，并将 AutoTonalRangeThresholdBright 参数设为 0.4。相机检测到您的图像中有 0.3% 的像素值小于或等于 52，有 0.4% 的像素值大于或等于 204。因此，暗阈值为 52，亮阈值为 204。

暗阈值与亮阈值示意图

示例代码#

C++ (Native)C++ (Generic)C#C (Generic)Python

// 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"

您也可以使用 pylon Viewer 轻松设置参数。