光学控制#

Optic Control 功能允许您控制光学设备，例如 Lenses。

此功能基于 SLP 协议，该协议支持相机、照明设备和光学设备（例如镜头）之间直接通信。

信息

当前 Basler Product Documentation 中不再包含不带 ILC 的旧款 Basler lights 以及已停产的 Basler Camera Lights 的文档。如果您需要有关这些产品的信息，请参考早期版本的离线文档，您可以点击此处进行下载。

信息

对于 dart M camera modules，目前仅在使用 Basler dart M 接口板（Interface Board ⁠dart M GigE RJ45 PoE 或 ⁠Interface Board dart M GigE RJ45 AUX）时方可使用 Optic Control 功能。

该功能的使用#

要使用 Optic Control 功能，您需要具备以下条件：

具有自动对焦功能的 Basler 镜头。
有关合适镜头的信息，请参阅 Partner Liquid Lens 主题中的 Optotune Lenses，或 Computar LensConnect Series with Variable Focal Length 主题中的 Partner Motorized Lenses 部分。
用于将光学镜头连接到相机的合适 Basler Lens Sync Cable。通过该同步电缆，您可以连接照明设备和镜头，并通过相机的单个 GPIO 端口进行控制。您所需的 Basler Sync Cable 取决于您想要操作的外围设备。
有关可用电缆变体及其支持的使用场景的信息，请参阅 Basler Sync Cables。
运行包含 Peripheral Device Control 功能的固件的兼容相机。

初始化光学设备#

在您可以使用光学设备之前，需要对其进行初始化。

要初始化您的光学设备：

按照 Preparing Peripheral Devices 和 Checking and Clearing Errors 中描述的步骤操作。
选择您要控制的光学设备。
对于第一个光学设备，设置 OpticControllerSelector 更改为 Optic1.
执行 OpticControllerInitialize 命令以初始化所连接的镜头。
根据镜头类型的不同，您可能会注意到其内部马达在运动。初始化时间也取决于镜头类型。
监视 OpticControllerStatus 参数。初始化完成后，该参数的值应为 Ready。如果不是，请参见下方的检查和清除错误。

根据所连接的镜头，只有该镜头支持的参数才可用于配置。

下表概述了光学设备内部的光学控制器可能具有的状态。

值	含义
Ready	光学设备已准备好使用。
Busy	光学设备当前正忙于处理操作，暂时无法接收新命令。
NotConnected	光学设备未连接到相机，或者无法被检测到。
NotInitialized	光学设备尚未初始化。要初始化该设备，请执行 `OpticControllerInitialize`命令。
错误	光学设备发生错误。有关详细信息，请参见 Error Statuses 表。
正在初始化	光学设备目前正在初始化。在此过程中，设备可能无法运行。

配置对焦#

手动对焦#

当你需要在预定义设置之间反复切换时，手动对焦是最佳选择。与自动对焦不同，它无需分析多张图像，因此运行速度快。速度取决于镜头类型：

液态镜头通常在大约 20 毫秒内切换到新的焦点。
对于电动镜头，速度取决于变化幅度：
从最近的对焦位置移动到最远的对焦位置比在中间位置之间切换需要明显更长的时间。

中提到的所有镜头该功能的使用以上支持使用以下各项进行对焦控制： FocusStepper 参数。参数值没有直接的物理意义。相反，镜头支持的对焦范围被映射到一个整数范围，其中 0 对应于最近的对焦距离，最大 FocusStepper 对应于最远的对焦距离。

某些经过校准的镜头还支持使用以下各项进行对焦控制： FocalPower 参数。该参数是一个浮点值，用于指定以屈光度为单位的镜头光焦度。

自动对焦#

相机可以自动调整镜头对焦，以在图像中实现最佳对焦。它使用相机图像传感器捕获的图像。

信息

自动对焦

自动对焦基于图像，并在用户定义的 ROI（感兴趣区域）内运行。必须将 ROI 3 用于自动对焦。
自动对焦 ROI 受到尺寸限制（最大 256 x 256 像素），且不能覆盖整个图像区域。因此，自动对焦仅评估配置的 Auto Function ROI 内的图像数据，而不是完整图像。
自动对焦过程需要采集多张图像。因此，实现对焦所需的时间在很大程度上取决于相机的帧率。较高的帧率通常会缩短自动对焦操作时间。

信息

自动对焦的图像要求

自动对焦需要图像中具有足够的对比度才能可靠运行。
均匀或低对比度的表面可能无法提供足够的图像细节来进行准确对焦。
边缘、条形码、文本和其他明显的结构可以显著提高自动对焦的性能和准确性。

要使用自动对焦：

自动对焦参数位于 Auto Function Control 特征树的类别。
打开此类别以进行调整。
在彩色相机上，使用 BslAutoFocusColorSelect 参数来选择用于自动对焦的颜色通道。
由于镜头的焦距还取决于光的波长，因此红光、绿光和蓝光的最佳对焦设置略有不同。对于大多数应用，默认设置 Green是一个不错的选择。
使用 BslAutoFocusStepperLowerLimit 和 BslAutoFocusStepperUpperLimit 来限制相机搜索的对焦范围。
如果您知道物体出现的距离范围，请将两个极值设置为对应的 FocusStepper 值。这可以显著加快自动对焦速度。
使用 FocusAutoMode 参数来选择相机自动控制对焦的方式。
- 在名称以 ImageBased开头的模式下，相机分析图像数据以评估当前场景的对焦情况。 ImageBased 是默认模式，适用于大多数情况。相机会在逐级调整对焦位置的同时捕获图像，以找到最佳对焦。
- ImageBasedFast 减少了捕获的图像数量，因此自动对焦完成得更快，但精度较低，在不利条件下可能会错过最佳对焦点。
- ImageBasedAccurate 可以提高精度，特别是在与上限和下限对焦限制配合使用时。
使用 Auto Function ROI 功能选择用于自动对焦的 ROI 3。
用于自动对焦的 ROI 3 最大尺寸限制为 256 x 256 像素。也可以使用更小的值。
开始采集图像。
自动对焦需要进行图像采集。
设置 FocusAuto 更改为 Once 以启动自动对焦。
相会在采集图像的同时调整对焦。操作完成后，它会将 FocusStepper 设置为找到的最佳值，并重置 FocusAuto 更改为 Off.

信息

即： FocalPower 参数仅在连接的镜头提供校准焦度值时可用。对该参数的支持取决于镜头制造商。

提高自动对焦速度#

为了减少自动对焦所需的时间，请考虑以下建议：

设置对焦限制（BslAutoFocusStepperLowerLimit 和 BslAutoFocusStepperUpperLimit）以限制自动对焦搜索最佳对焦位置的范围。
在自动对焦操作期间减小 Image ROI，以最大限度提高可实现的帧率并使自动对焦更快完成。
使用支持快速对焦调节的高速镜头。

配置光圈#

如果镜头支持光圈控制，您可以使用 ApertureStepper 参数来调整光圈开度。该参数值并不代表物理光圈（f数）。相反，它将镜头支持的光圈范围映射到一个整数范围，其中值为 0 对应最大光圈开度，最大 ApertureStepper 值代表最小光圈开度。

配置焦距#

如果镜头支持焦距控制，请使用 FocalLengthStepper 参数来调整其焦距（即变焦）。该参数值没有直接的物理意义。相反，它将镜头支持的焦距范围映射到一个整数范围，其中 0 对应最短焦距，最大 FocalLengthStepper 值对应镜头支持的最长焦距。

更改焦距后，对焦位置可能会发生偏移，因此您可能需要重新调整对焦。

检查和清除错误#

错误状态#

即： BslPeripheralDeviceErrorStatus 参数可采用以下值：

值	含义
通信故障	如果光学设备与相机之间的数据传输出现故障，将会发生通信错误。这可能是由电缆太长或线路上的噪声过大引起的。
连接丢失	与先前连接的光学设备的连接已丢失。例如，如果电缆松动，可能会发生这种情况。
无错误	未检测到错误。
未连接	光学设备未连接到相机或尚未被枚举。执行 `BslPeripheralEnumerateDevices` 命令以枚举设备。
不支持的设备版本	该光学设备与当前相机不兼容。请联系支持部门以了解是否有可用的固件更新。

示例代码#

信息

这些代码示例仅适用于在其固件中包含 Peripheral Devices Control 功能的 ace 2、boost R 和 dart M 相机。

ace 2、boost R、dart M 相机#

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

// Select and initialize the optic controller.
camera.OpticControllerSelector.SetValue(OpticControllerSelector_Optic1);
camera.OpticControllerInitialize.Execute();

// Set focus position manually using stepper (0 = nearest focus position).
camera.FocusStepper.SetValue(1000);

// Set focus position manually using focal power (0 = nearest focus position).
camera.FocalPower.SetValue(1.0);

// Set aperture (0 = maximum aperture opening).
camera.ApertureStepper.SetValue(50);

// Set focal length (0 = shortest focal length).
camera.FocalLengthStepper.SetValue(200);

// Configure the autofocus ROI.
camera.AutoFunctionROISelector.SetValue(AutoFunctionROISelector_ROI3);
camera.AutoFunctionROIUseFocus.SetValue(true);
camera.AutoFunctionROIWidth.SetValue(128);
camera.AutoFunctionROIHeight.SetValue(128);
camera.AutoFunctionROIOffsetX.SetValue(840);
camera.AutoFunctionROIOffsetY.SetValue(480);

// Use the green color channel for focus evaluation.
camera.BslAutoFocusColorSelect.SetValue(BslAutoFocusColorSelect_Green);

// Restrict the autofocus search range.
// Limiting the range speeds up the focusing process.
camera.BslAutoFocusStepperLowerLimit.SetValue(800);
camera.BslAutoFocusStepperUpperLimit.SetValue(1200);

// Configure autofocus behavior.
camera.FocusAutoMode.SetValue(FocusAutoMode_ImageBased);

// Start autofocus.
camera.FocusAuto.SetValue(FocusAuto_Once);

INodeMap& nodemap = camera.GetNodeMap();
// Select and initialize the optic controller.
CEnumParameter(nodemap, "OpticControllerSelector").SetValue("Optic1");
CCommandParameter(nodemap, "OpticControllerInitialize").Execute();

// Set focus position manually using stepper (0 = nearest focus position).
CIntegerParameter(nodemap, "FocusStepper").SetValue(1000);

// Set focus position manually using focal power (0 = nearest focus position).
CFloatParameter(nodemap, "FocalPower").SetValue(1.0);

// Set aperture (0 = maximum aperture opening).
CIntegerParameter(nodemap, "ApertureStepper").SetValue(50);

// Set focal length (0 = shortest focal length).
CIntegerParameter(nodemap, "FocalLengthStepper").SetValue(200);

// Configure autofocus ROI.
CEnumParameter(nodemap, "AutoFunctionROISelector").SetValue("ROI3");
CBooleanParameter(nodemap, "AutoFunctionROIUseFocus").SetValue(true);
CIntegerParameter(nodemap, "AutoFunctionROIWidth").SetValue(128);
CIntegerParameter(nodemap, "AutoFunctionROIHeight").SetValue(128);
CIntegerParameter(nodemap, "AutoFunctionROIOffsetX").SetValue(840);
CIntegerParameter(nodemap, "AutoFunctionROIOffsetY").SetValue(480);

// Use the green color channel for focus evaluation.
CEnumParameter(nodemap, "BslAutoFocusColorSelect").SetValue("Green");

// Restrict the autofocus search range.
// Limiting the range speeds up the focusing process.
CIntegerParameter(nodemap, "BslAutoFocusStepperLowerLimit").SetValue(800);
CIntegerParameter(nodemap, "BslAutoFocusStepperUpperLimit").SetValue(1200);

// Configure autofocus behavior.
CEnumParameter(nodemap, "FocusAutoMode").SetValue("ImageBased");

// Start autofocus.
CEnumParameter(nodemap, "FocusAuto").SetValue("Once");

// Select and initialize the optic controller.
camera.Parameters[PLCamera.OpticControllerSelector].SetValue(PLCamera.OpticControllerSelector.Optic1);
camera.Parameters[PLCamera.OpticControllerInitialize].Execute();

// Set focus position manually using stepper (0 = nearest focus position).
camera.Parameters[PLCamera.FocusStepper].SetValue(1000);

// Set focus position manually using focal power (0 = nearest focus position).
camera.Parameters[PLCamera.FocalPower].SetValue(1.0);

// Set aperture (0 = maximum aperture opening).
camera.Parameters[PLCamera.ApertureStepper].SetValue(50);

// Set focal length (0 = shortest focal length).
camera.Parameters[PLCamera.FocalLengthStepper].SetValue(200);

// Configure autofocus ROI.
camera.Parameters[PLCamera.AutoFunctionROISelector].SetValue(PLCamera.AutoFunctionROISelector.ROI3);
camera.Parameters[PLCamera.AutoFunctionROIUseFocus].SetValue(true);
camera.Parameters[PLCamera.AutoFunctionROIWidth].SetValue(128);
camera.Parameters[PLCamera.AutoFunctionROIHeight].SetValue(128);
camera.Parameters[PLCamera.AutoFunctionROIOffsetX].SetValue(840);
camera.Parameters[PLCamera.AutoFunctionROIOffsetY].SetValue(480);

// Use the green color channel for focus evaluation.
camera.Parameters[PLCamera.BslAutoFocusColorSelect].SetValue(PLCamera.BslAutoFocusColorSelect.Green);

// Restrict the autofocus search range.
// Limiting the range speeds up the focusing process.
camera.Parameters[PLCamera.BslAutoFocusStepperLowerLimit].SetValue(800);
camera.Parameters[PLCamera.BslAutoFocusStepperUpperLimit].SetValue(1200);

// Configure autofocus behavior.
camera.Parameters[PLCamera.FocusAutoMode].SetValue(PLCamera.FocusAutoMode.ImageBased);

// Start autofocus.
camera.Parameters[PLCamera.FocusAuto].SetValue(PLCamera.FocusAuto.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 */
/* Select and initialize the optic controller. */
errRes = PylonDeviceFeatureFromString(hdev, "OpticControllerSelector", "Optic1");
CHECK(errRes);
errRes = PylonDeviceExecuteCommandFeature(hdev, "OpticControllerInitialize");
CHECK(errRes);

/* Set focus position manually using stepper (0 = nearest focus position). */
errRes = PylonDeviceSetIntegerFeature(hdev, "FocusStepper", 1000);
CHECK(errRes);

/* Set focus position manually using focal power (0 = nearest focus position). */
errRes = PylonDeviceSetFloatFeature(hdev, "FocalPower", 1.0);
CHECK(errRes);

/* Set aperture (0 = maximum aperture opening). */
errRes = PylonDeviceSetIntegerFeature(hdev, "ApertureStepper", 50);
CHECK(errRes);

/* Set focal length (0 = shortest focal length). */
errRes = PylonDeviceSetIntegerFeature(hdev, "FocalLengthStepper", 200);
CHECK(errRes);

/* Configure autofocus ROI. */
errRes = PylonDeviceFeatureFromString(hdev, "AutoFunctionROISelector", "ROI3");
CHECK(errRes);
errRes = PylonDeviceSetBooleanFeature(hdev, "AutoFunctionROIUseFocus", 1);
CHECK(errRes);
errRes = PylonDeviceSetIntegerFeature(hdev, "AutoFunctionROIWidth", 128);
CHECK(errRes);
errRes = PylonDeviceSetIntegerFeature(hdev, "AutoFunctionROIHeight", 128);
CHECK(errRes);
errRes = PylonDeviceSetIntegerFeature(hdev, "AutoFunctionROIOffsetX", 840);
CHECK(errRes);
errRes = PylonDeviceSetIntegerFeature(hdev, "AutoFunctionROIOffsetY", 480);
CHECK(errRes);

/* Use the green color channel for focus evaluation. */
errRes = PylonDeviceFeatureFromString(hdev, "BslAutoFocusColorSelect", "Green");
CHECK(errRes);

/* Restrict the autofocus search range. */
/* Limiting the range speeds up the focusing process. */
errRes = PylonDeviceSetIntegerFeature(hdev, "BslAutoFocusStepperLowerLimit", 800);
CHECK(errRes);
errRes = PylonDeviceSetIntegerFeature(hdev, "BslAutoFocusStepperUpperLimit", 1200);
CHECK(errRes);

/* Configure autofocus behavior. */
errRes = PylonDeviceFeatureFromString(hdev, "FocusAutoMode", "ImageBased");
CHECK(errRes);

/* Start autofocus. */
errRes = PylonDeviceFeatureFromString(hdev, "FocusAuto", "Once");
CHECK(errRes);

# Select and initialize the optic controller.
camera.OpticControllerSelector.Value = "Optic1"
camera.OpticControllerInitialize.Execute()

# Set focus position manually using stepper (0 = nearest focus position).
camera.FocusStepper.Value = 1000

# Set focus position manually using focal power (0 = nearest focus position).
camera.FocalPower.Value = 1.0

# Set aperture (0 = maximum aperture opening).
camera.ApertureStepper.Value = 50

# Set focal length (0 = shortest focal length).
camera.FocalLengthStepper.Value = 200

# Configure autofocus ROI.
camera.AutoFunctionROISelector.Value = "ROI3"
camera.AutoFunctionROIUseFocus.Value = True
camera.AutoFunctionROIWidth.Value = 128
camera.AutoFunctionROIHeight.Value = 128
camera.AutoFunctionROIOffsetX.Value = 840
camera.AutoFunctionROIOffsetY.Value = 480

# Use the green color channel for focus evaluation.
camera.BslAutoFocusColorSelect.Value = "Green"

# Restrict the autofocus search range.
# Limiting the range speeds up the focusing process.
camera.BslAutoFocusStepperLowerLimit.Value = 800
camera.BslAutoFocusStepperUpperLimit.Value = 1200

# Configure autofocus behavior.
camera.FocusAutoMode.Value = "ImageBased"

# Start autofocus.
camera.FocusAuto.Value = "Once"

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