光學控制#

Optic Control 功能允許您控制光學設備，例如 Lenses。

該功能基於 SLP 協定，可讓相機、照明設備與光學設備（例如鏡頭）直接相互通訊。

資訊

當前的 Basler 產品說明文件中不再包含舊款不支援 ILC 的 Basler 照明設備以及已停產的 Basler Camera Lights 的說明。如果您需要這些產品的資訊，請參閱早期版本的離線說明文件，您可以點擊這裡進行下載。

資訊

對於 dart M camera modules，Optic Control 功能目前僅在使用 Basler dart M interface board（即 Interface Board ⁠dart M GigE RJ45 PoE 或 ⁠Interface Board dart M GigE RJ45 AUX）時可用。

使用此功能#

若要使用 Optic Control 功能，您需要具備以下條件：

具備自動對焦功能的 Basler Lens。
有關適合的鏡頭資訊，請參閱 Partner Liquid Lens 主題中的 Optotune Lenses，或 Partner Motorized Lenses 主題中的 Computar LensConnect Series with Variable Focal Length 部分。
一條合適的 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。如果不是，請參閱檢查與清除錯誤下方。

根據所連接的鏡頭，僅可設定該鏡頭支援的參數。

下表概述了光學設備內部的光學控制器可能具有的狀態。

Value	含義
Ready	光學設備已準備好使用。
Busy	光學設備目前正忙於處理操作，暫時無法接受新指令。
NotConnected	光學裝置未連接至相機，或者無法被偵測到。
NotInitialized	光學裝置尚未初始化。若要初始化裝置，請執行 `OpticControllerInitialize`命令。
錯誤	光學裝置發生錯誤。如需詳細資訊，請參閱 Error Statuses 表格。
Initializing	光學裝置目前正在初始化。在此過程中，裝置可能無法進行操作。

設定對焦#

手動對焦#

當您需要在預先定義的設定之間重複切換時，手動對焦是最佳選擇。與自動對焦不同，它不需要分析多個影像，因此操作速度快。速度取決於鏡頭類型：

液態鏡頭通常在大約 20 毫秒內即可切換至新的對焦。
對於電動鏡頭，速度取決於變化的幅度：
從最近的對焦位置移動到最遠的對焦位置，所需的時間明顯長於在中間位置之間切換的時間。

中提及的所有鏡頭使用此功能以上支援使用下列項目進行對焦控制： FocusStepper 參數。此參數值沒有直接的物理意義。相反地，鏡頭支援的對焦範圍會對應至一個整數範圍，其中 0 對應至最近的對焦距離，而最大值 FocusStepper 則對應至最遠的對焦距離。

部分經過校正的鏡頭也支援使用下列項目進行對焦控制： FocalPower 參數。此參數是一個浮點數值，用於指定以屈光度表示的鏡頭光焦度。

自動對焦#

相機可以自動調整鏡頭對焦，以在影像中達到最佳對焦效果。它使用相機影像感測器擷取的影像。

資訊

自動對焦

自動對焦基於影像，並在使用者定義的 ROI (Region of Interest) 內運作。自動對焦必須使用 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 值對應鏡頭支援的最長焦距。

更改焦距後，對焦位置可能會偏移，因此您可能需要重新調整對焦。

檢查與清除錯誤#

Error Statuses#

影像 BslPeripheralDeviceErrorStatus 參數可接受下列值：

Value	含義
Communication Error	如果光學裝置與相機之間的資料傳輸發生故障，就會發生通訊錯誤。這可能是由於使用過長的纜線或線路上的雜訊過多所致。
Connection Lost	與先前連接的光學裝置的連接已中斷。例如，如果纜線鬆脫，就可能會發生這種情況。
No Error	未偵測到錯誤。
Not Connected	光學裝置未連接到相機或尚未列舉。執行 `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 來輕鬆設定參數。