使用 GenTL Interface#

本主題說明如何使用 Basler Framegrabber SDK 的 GenTL Producer。

GenTL Producer 是一個實作 GenICam GenTL 傳輸層介面的程式庫。GenTL Consumer 是透過該介面載入一或多個 Producer 的任何應用程式或程式庫，例如 pylon、HALCON 或您自己的軟體。所實作的 Producer 提供 GenICam GenTL Standard 1.5。

透過 GenTL Producer，您可以執行下列操作：

透過相同的介面 (GenApi) 設定相容於 GenICam 的 Camera Link 與 CoaXPress 相機。
檢視影像擷取系統的階層架構。
開發通用應用程式 (GenTL 消費者)，而無需考量所使用的相機標準。

開啟 GenTL Producer#

目錄 <Framegrabber SDK installation directory>/bin 包含兩個 GenTL Producer 檔案：

Producer	傳輸技術
ProducerCL.cti	Camera Link
ProducerCXP.cti	CoaXPress

.cti 檔案可用於識別 GenTL Producer。該副檔名代表 Common Transport Interface（通用傳輸介面）。

切勿直接開啟 GenTL Producer。請開啟 GenTL consumer，例如 pylon。當 GENICAM_GENTL64_PATH 或 GENICAM_GENTL32_PATH 環境變數設定正確時，consumer 便會載入 GenTL Producer。每個變數包含一個或多個 producer 目錄。Framegrabber SDK 會新增 <Framegrabber SDK installation directory>/bin 設定為 GENICAM_GENTL64_PATH 或 GENICAM_GENTL32_PATH。安裝或移除套件後，請確認 GENICAM_GENTL64_PATH 或 GENICAM_GENTL32_PATH 環境變數僅包含一個 Basler producer 路徑。如需關於如何在 GENICAM_GENTL64_PATH 當 pylon 與 Framegrabber SDK 平行安裝時，請參閱並行安裝 pylon 與 Framegrabber SDK.

GenTL 組態檔#

GenTL Producer 會在以下目錄中為每個偵測到的擷取卡儲存組態檔：

Windows：%AppData%\basler
Linux：~/.config/basler

.config 檔案儲存了該擷取卡的 Producer 設定，例如所選的 Applet、探索方法以及相機通訊協定組態。如果您刪除該檔案，Producer 會將該擷取卡的組態重設為預設值。刪除檔案之前請先關閉 Consumer，之後再重新開啟 Consumer。

此組態具備持續性，且屬於該擷取卡所有。您在某個應用程式工作階段中進行的設定，在下一個工作階段以及不同的 GenTL Consumer 中仍然有效。請將儲存的設定視為擷取卡的現用設定檔。這些設定並非設定它們的應用程式的暫時選項。如需關於變更後的設定何時生效的詳細資訊，請參閱套用與保留變更。

GenTL 模組階層#

GenTL 將擷取系統以模組階層的形式呈現給 consumer：

Module	在 Framegrabber SDK 中的表示方式
`System`	Producer 本身。此模組是階層的進入點。
`Interface`	一塊擷取卡。
`Device`	一台相機，或代表擷取通道的虛擬裝置。
`Data Stream`	裝置的一個擷取串流。
`Buffer`	為影像擷取所宣告的 Memory。

Consumer 可以不同的方式顯示此階層。本主題中的 GenApi 功能名稱在每個 consumer 中都是相同的。以下章節中的大部分組態都屬於 Interface 模組。它屬於擷取卡，而非相機。

Interface Applets#

影像 Interface 模組會列出 InterfaceApplets 類別中可用的 Applet。在 InterfaceApplets > InterfaceApplet，您可以選取 Applet 或 .hap 當前載入檔案以外的檔案。

Producer 會將 Applet 的變更儲存在持續性 GenTL 組態檔中。該變更僅在您關閉所有裝置並更新裝置清單後，或者在關閉並重新開啟 Interface後才會生效。選取 Applet 並更新裝置後，請稍候幾秒鐘。然後檢查 InterfaceAppletStatus 以查看是否已載入 Applet。

擷取卡類型決定了哪些 Applet 可用：

採集卡	Applet 可用時機...
imaWorx, imaFlex	該 Applet 存在於檔案系統中，即 Framegrabber SDK 安裝目錄下的 DLL 或 Hardware Applets 子目錄中。請執行包含該 Applet 的 Applet 安裝程式，或將 VisualApplets .hap 檔案複製到 Hardware Applets 資料夾中（例如 …\Basler\FramegrabberSDK5.x.x\Hardware Applets）。
marathon	該 Applet 已燒錄至擷取卡上。如果尚未燒錄，請先進行燒錄。如需詳細資訊，請參閱將 Applet 燒錄至 marathon Frame Grabbers。

如需有關在 microDiagnostics 中管理 Applet 的詳細資訊，請參閱管理 Applet (microDiagnostics)。

透過 User Sets 進行 Applet 組態#

MCF 檔案用於儲存 Applet 設定。MCF 代表 microEnable Configuration File。副檔名為 .mcf。如需詳細資訊，請參閱MCF 檔案。

在 UserSetControl 類別的 Interface 模組，您可儲存與載入目前所選 Applet 的設定。若要儲存或載入該設定，請輸入現有或新檔案的路徑 *.mcf 檔案路徑於 UserSetFile 參數中輸入現有或新 *.mcf 檔案的路徑。然後執行 UserSetSave 或 UserSetLoad。如果路徑為空白，或副檔名不是 .mcf，則這兩個命令將無法使用。

其中涉及兩個不同的設定檔。它們具有不同的範圍和生命週期：

檔案	Contains	存留期
*.mcf	單一 Applet 的參數值。	Producer 會透過以下方式按需載入這些值 `UserSetLoad`。非持久性：在變更 Applet 或關閉系統後，Producer 不會保留這些值。
*.config	單一擷取卡的 GenTL Producer 設定。	持久性：Producer 每次初始化時都會自動重新載入此檔案 `Interface`.

如果目前載入的 Applet 與載入的 .mcf 檔案所參照的 Applet 不符，Producer 會先嘗試設定 InterfaceApplet 設為設定檔中的 Applet。關閉裝置並更新裝置清單。請勿關閉 System。隨後設定將會生效。

裝置探索與虛擬裝置#

影像 DiscoveryMethod 功能（Interface.DiscoveryMethod in Interface > TransportLayerControl）時，都會自動重新載入此檔案，該功能定義了更新裝置清單時 Producer 建立哪些裝置。

Discovery Modes Overview#

`DiscoveryMethod`	公開的裝置	預設值
`EmulationDiscovery`	Applet 的每個擷取通道對應一個虛擬裝置。不會搜尋實體相機。	Camera Link
`MixedDiscovery`	會搜尋實體相機。在 Camera Link 上，搜尋會使用 GenCP 或 CLP。未發現相機的擷取通道將以虛擬裝置填滿。	—
`CameraDiscovery`	僅搜尋並公開實體相機。不會建立虛擬裝置。	CoaXPress

偽裝置（模擬裝置）可讓 Applet 及其擷取通道在無法偵測到相機時也能使用。對於每個偽裝置，Producer 會產生一個基本的遠端裝置 XML 檔案。如果 Applet 包含影像產生器，Producer 預設會啟用該影像產生器。若要從連接的 Camera Link 相機接收影像，請停用遠端裝置節點中的影像產生器。

請根據預期用途選擇探索模式：

EmulationDiscovery：當您開發或檢查 Applet、未連接相機，或者必須在無需相機控制的情況下存取 Applet 參數與擷取通道參數時，請使用此模式。真實相機探索功能會被停用，且不會使用相機協定設定。
MixedDiscovery：當必須尋找實體相機且空的擷取通道必須保持可作為虛擬裝置存取時，請使用此模式。在 Camera Link 上，透過 GenCP 或 CLP 搜尋實體相機。對於 VisualApplets 也請使用此模式 .hap 檔案，包括 CXP 擷取卡上的檔案。如需詳細資訊，請參閱搭配 GenTL 使用 VisualApplets Applet.
CameraDiscovery：當應用程式必須僅列出真實相機時，請使用此模式。

對於 Camera Link，真實相機探索也需要相機通訊協定。如需詳細資訊，請參閱 Accessing Camera Link Cameras。

Compatibility Status#

影像 CompatibilityStatus category 會回報目前擷取卡、Applet 與相機的組合是否能夠協同運作。

介面模組（擷取卡）#

功能	回報的值
`InterfaceDriverVersion`	此項目的驅動程式版本號碼 `Interface`.
`InterfaceProducerVersion`	GenTL Producer 的版本號碼。
`InterfacePCIeStatus`	如果 PCIe 速度達到或超過所需速度，此 Property 會顯示偵測到的 PCIe 速度（例如 `Gen3x8`)。否則，此 Property 會顯示警告，例如 `Warning: Gen2x1 detected, but Gen3x8 possible`。降級的連線會限制可用的頻寬。
`InterfacePowerSupplyStatus`	如果已連接擷取卡的電源接頭，此 Property 顯示 `Connected` 。 `Warning: PCI-Power connector missing` 如果未連接電源接頭，此 Property 顯示

在 pylon Viewer 中， Compatibility Status 中，以了解 Interface 模組外觀如下：

pylon Viewer Compatibility Status Interfaces

裝置模組（相機）#

功能	回報的值
`DevicePixelformatStatus`	如果已連接擷取卡的電源接頭，此 Property 顯示 `Supported` （前提是相機支援所設定的 Pixel Format）。否則，此 Property 會顯示 `Warning: Not supported`.
`DeviceAutomaticROIControlStatus`	如果已連接擷取卡的電源接頭，此 Property 顯示 `Activated` （預設情況下），或顯示 `Deactivated` （如果已停用 Automatic ROI）。在 pylon Viewer 中，請停用 `Automatic ROI` 位於 `Device Transport Layer` > `Image Format Control`。當相機的步進大小（Step Size）與 Applet 的步進大小不同，且 ROI 已調整為下一個符合的值時，此 Property 會顯示 `Warning: ROI truncated according to stepping`
`DeviceTapGeometryStatus`	如果已連接擷取卡的電源接頭，此 Property 顯示 `Supported` （如果找到相符的 Tap geometry）。否則，此 Property 會顯示 `Warning: Driver does not support tap geometry setting` 或 `Warning: Requested geometry not supported in applet`.

Tap geometry（輸出通道幾何形狀）描述了傳輸感光元件資料的方式。透過 1X_1Y（這是大多數相機的預設值），整個影像會作為單一資料流進行傳輸。大型且高速的感光元件可能需要 1X_2YE。在該模式下，感光元件會同時讀出兩個子畫面（Subframe）。僅在相機需要且 Applet 支援的情況下才設定 1X_2YE 。

在 pylon Viewer 中， Compatibility Status 中，以了解 Device 模組外觀如下：

pylon Viewer Compatibility Status Devices

自動 ROI 與格式#

在 ImageFormatControl 類別的 Device 模組中，您可以找到 AutomaticFormatControl, AutomaticROIControl, AutomaticTapGeometryControl的狀態，以及 OutputPacketFormats nodes（節點）。當 AutomaticFormatControl, AutomaticROIControl的狀態，以及 AutomaticTapGeometryControl 處於啟用狀態時，GenTL Producer 會設定 Applet 的格式、ROI 和 Tap geometry，使其與相機設定相符，因此您只需要設定相機和 Applet 各一次。此行為適用於 microEnable 6 擷取卡的 Applet。

當 applet 必須保留其自身的組態時，請停用這些功能。這特別適用於使用 VisualApplets 設計的 applet。如需詳細資訊，請參閱 Using VisualApplets Applets with GenTL。

存取 Camera Link 相機#

ProducerCL.cti 可以探索 Camera Link 相機並提供完整的 GenApi 存取權限，包含相機的 XML 描述檔案。此存取權限對於第三方 Camera Link 相機非常有用，因為大多數 GenTL Producer 不會為這些相機提供 XML 存取權限。以下章節說明支援的兩種相機通訊協定及其組態方式。

為什麼 Camera Link 需要已設定的通訊協定#

在 Camera Link 上，您需要設定相機協定。系統不會自動偵測此協定。Camera Link 將影像傳輸和串列連線標準化，但並未將透過該串列線控制相機的方式標準化。每個廠商都實作了自己的命令協定。由於沒有可供優先嘗試的標準協定，因此無法進行自動偵測。使用任意協定變體進行探測需要花費太長時間，並且可能會使某些相機模型進入未定義的狀態。

GenApi 需要導向暫存器的存取權限：讀取此位址、寫入彼位址。相機的 XML 檔案即描述了此存取權限。有兩個標準化路徑可將串列線連接至此暫存器模型：

路由	如何彌補差距	相機專屬部分的位置
GenCP	相機本身在序列線上實作了標準化的封包式暫存器存取通訊協定。	相機韌體。主機上不需要任何廠商軟體。
CLP (CLProtocol)	來自相機廠商的通訊協定程式庫將 GenApi 暫存器存取轉譯為廠商專屬的序列通訊協定。	安裝在主機上的 CLProtocol 程式庫（.dll 檔案）。

這兩條路徑無法互換。具有廠商 CLP Library 的相機無法理解 GenCP。GenCP 相機不需要 CLP Library。

資訊

Basler Camera Link 相機與 GenCP 不相容，但它們支援 CLP。安裝 Basler CLProtocol Library 後，ProducerCL 便能直接存取相機的 XML 檔案以及完整的相機設定。

GenCP (Generic Control Protocol) 是針對暫存器型裝置的 GenICam 標準。相機會在序列線上回應標準化的讀取與寫入指令。這些指令從 9600 baud 的 Camera Link 喚醒速率開始。相機會透過啟動載體暫存器對公開其身分，並透過該暫存器空間中的資訊清單提供其 GenICam XML 檔案。所有相機專屬的內容都包含在韌體中，因此 GenCP 相機無需在主機上安裝廠商專屬的軟體即可運作。

CLP (CLProtocol) 是適用於所有其他 Camera Link 相機的 GenICam 標準。廠商的 CLProtocol 程式庫為 GenApi 提供暫存器介面，並將該介面轉譯為相機本身的序列通訊協定。對於基於 ASCII 的相機，該程式庫提供擬真暫存器空間與對應的 XML 描述。會針對各個廠商安裝 CLProtocol 程式庫，並透過 GENICAM_CLPROTOCOL 環境變數進行註冊。在每個已註冊的目錄下方，適用於 64 位元 Windows 應用程式的程式庫位於 Win64_x64 子目錄中。對於 Basler 程式庫，檔案為 \Win64_x64\BaslerClProtocol.dll.

Automatic Configuration for Basler CLP#

影像 ConfigurationForBaslerCLP feature（功能）可為 Basler Camera Link 相機提供自動設定。此功能預設為啟用。在 Interface 初始化時，Producer 會檢查是否可以透過 BaslerClProtocol.dll 找到 GENICAM_CLPROTOCOL。如果 Producer 找到該函式庫，將會進行以下變更：

將 DiscoveryMethod 設定為 MixedDiscovery.
將 ClpSharedLibraryPath 至檢測到的 BaslerClProtocol.dll.

唯讀 Property BaslerCLPAutoConfigActive 表示自動設定正在生效。更新裝置清單後，請在下列位置確認載入的函式庫： LoadedClpSharedLibraryPath.

當自動設定處於啟用狀態時，它會控制 DiscoveryMethod 和 ClpSharedLibraryPath。若要手動設定其中任一 Property，請先設定 ConfigurationForBaslerCLP 設定為 false.

手動協議選擇#

您設定的協定（GenCP 或 CLP）取決於相機。請在設定協定前 ConfigurationForBaslerCLP 設定為 false 設定

對於 GenCP（當未配置 CLP 庫時，用於真實相機發現的預設協議）：

步驟	功能	Value
1	`ConfigurationForBaslerCLP`	`false`
2	`ClpSharedLibraryPath`	空白
3	`DiscoveryMethod`	`MixedDiscovery` 或 `CameraDiscovery`

對於帶有供應商庫的 CLP：

步驟	功能	Value
1	`ConfigurationForBaslerCLP`	`false`
2	`ClpSharedLibraryPath`	供應商的 CLProtocol 庫的完整路徑（.dll 或 .so 檔案），通常位於註冊表中註冊的目錄中 `GENICAM_CLPROTOCOL`
3	`DiscoveryMethod`	`MixedDiscovery` 或 `CameraDiscovery`

更新裝置清單後，請在下列位置驗證結果： LoadedClpSharedLibraryPath. ClpSharedLibraryPath 僅儲存要求的路徑。 LoadedClpSharedLibraryPath 回報實際載入的函式庫。

Camera Link 功能參考#

所有 Property 均位於 Interface > TransportLayerControl:

功能	目的
`ConfigurationForBaslerCLP`	啟用自動 Basler 設定。此 Property 預設為啟用。若要手動設定協定，請先將其停用。
`BaslerCLPAutoConfigActive`	唯讀。表示自動設定處於啟用狀態，且已找到 Basler CLProtocol 函式庫。
`DiscoveryMethod`	選擇真實相機、偽設備或兩者兼具。如需更多資訊，請參閱設備發現與偽設備。
`ClpSharedLibraryPath`	要求的 CLProtocol 函式庫完整路徑。空白路徑會選取 GenCP 用於實體相機偵測。
`LoadedClpSharedLibraryPath`	唯讀。實際載入的 CLProtocol 函式庫。

下表顯示典型組態：

預期用途	`ConfigurationForBaslerCLP`	`DiscoveryMethod`	`ClpSharedLibraryPath`
僅限 Applet 或取像通道，無實體相機	`false`	`EmulationDiscovery`	未使用
Basler Camera Link 相機	`true`	自動控制 (`MixedDiscovery`)	自動控制（BaslerClProtocol.dll）
相容 GenCP 的相機	`false`	`MixedDiscovery` 或 `CameraDiscovery`	空白
帶有供應商 CLP 庫的相機	`false`	`MixedDiscovery` 或 `CameraDiscovery`	供應商庫的完整路徑

序列連接是如何建立的#

CLProtocol 庫不直接與擷取卡通訊。該庫從載入該庫的軟體接收序列介面 (ISerial)。當該庫在 ProducerCL 內部執行時，producer 會提供其自身的內部 ISerial 實作。對擷取卡的存取保留在 producer 內部，不涉及額外的序列元件。

獨立的 CLProtocol 用戶端（例如 pylon）不在 GenTL 內執行。這些用戶端透過以下方式取得序列介面： CLAllSerial. CLAllSerial 在註冊表值下註冊的目錄中發現 Camera Link Serial 庫（clser*.dll）。通常，該目錄為 HKEY_LOCAL_MACHINE\SOFTWARE\CameraLink\CLSERIALPATH。通常，該目錄是 C:\Program Files\CameraLink\Serial。在該目錄中， clsersis.dll 為 Basler 擷取卡實作 Camera Link Serial。

兩條路徑最終都指向相同的硬體。無法同時透過這兩條路徑初始化擷取卡。這項限制主要在安裝 pylon 時較為重要。本主題未說明如何將 ProducerCL.cti 作為 pylon 傳輸層使用。如需更多資訊，請參閱並行安裝 pylon 與 Framegrabber SDK。

Applying and Persisting Changes#

對 DiscoveryMethod、Applet 選擇以及 GenCP 或 CLP 設定只有在您更新裝置清單後才會生效。在某些情況下，變更只有在您關閉並重新開啟 Interface 或重新啟動 consumer 後才會生效。請在套用完整的組態之前進行設定。套用組態後，請評估結果。

此組態會針對每個擷取卡進行儲存，並在不同的工作階段之間保持有效，即使在關閉 producer 後也是如此。如需詳細資訊，請參閱 GenTL Configuration。當預期用途變更時，請記住以下幾點：

持久化的 EmulationDiscovery 設定會阻止尋找實體相機。這是刻意設計的。
持久化的 CameraDiscovery 當所選通訊協定無法識別相機時，設定不會建立虛擬裝置。
在更換相機後，持久化的 CLP 路徑將繼續選擇該供應商庫。
啟用 Basler 自動組態後，每當初始化 MixedDiscovery 時，它都會還原 Interface 和 Basler CLP 路徑。

Interface 某些 Consumer 中的節點存取

在某些 consumer（例如 HALCON）中， Interface node map is available only when at least one device is detected. If DiscoveryMethod 且 CameraDiscovery 且通訊協定與相機不符，producer 將不會建立任何裝置。因此，您將無法在該 consumer 中存取探索設定。請尋找與擷取卡序號相關聯的組態檔。在 Windows 上，該檔案位於 %AppData%\basler。在 Linux 上，該檔案位於 ~/.config/basler。請變更該檔案中的探索設定，或刪除該檔案以重設組態。若為僅 applet 的設定，請使用 EmulationDiscovery to avoid this situation. That mode always creates pseudo devices.

搭配 GenTL 使用 VisualApplets Applet#

設計考量#

Applet file name: Applet 的檔案名稱會直接用作 Name attribute of the corresponding entry in the InterfaceApplets enumeration. The file name must therefore conform to the GenICam naming requirements. GenICam standard version 2.1.1 specifies the following requirements:

Each node has a Name attribute. The Name must be unique within the camera description
file. Names can be composed of alphanumeric characters [A-Za-z0-9]. The schema also
allows the use of the underscore '_', but not as a leading character.

Operator and hierarchy names: Applet 的參數名稱是由 VisualApplets 設計的 operator 階層所組成。Producer 會變更這些名稱，使其符合 GenICam 的要求。如果您從一開始就根據 GenApi 規則來命名 operator 實例和階層元素，所產生的節點名稱會更容易理解。

執行階段組態#

When you use an applet that was designed with VisualApplets, the usual camera discovery isn't sufficient. The producer also doesn't synchronize camera parameters to the applet automatically. Make the following settings:

設定 DiscoveryMethod 設定為 MixedDiscovery before you enumerate the devices. This setting enables all DmaToPc module.
After you open a device, set AutomaticFormatControl, AutomaticROIControl的狀態，以及 AutomaticTapGeometryControl in the device XML to false.

故障排除#

觀察到的行為	判讀與處置
`DiscoveryMethod` 或 `ClpSharedLibraryPath` can't be edited for a Camera Link `Interface`.	自動 Basler 組態已啟用。請先設定 `ConfigurationForBaslerCLP` 設定為 `false` 。
Camera Link 僅列出虛擬裝置 `Interface`.	`EmulationDiscovery` is active, or `MixedDiscovery` 未找到真實相機，並以虛擬裝置填滿通道。請檢查通訊協定組態。
未發現 Basler Camera Link 相機。	保留 `ConfigurationForBaslerCLP` enabled. Make sure that `GENICAM_CLPROTOCOL` 指向 Basler CLProtocol 安裝。更新裝置清單並確認 BaslerClProtocol.dll in `LoadedClpSharedLibraryPath`.
設定 CLP 後，未發現相容於 GenCP 的相機。	設定 `ConfigurationForBaslerCLP` 設定為 `false`, clear `ClpSharedLibraryPath`，請選取 `MixedDiscovery` 或 `CameraDiscovery`，並更新裝置清單。
未發現具備廠商 CLP 程式庫的相機。	設定 `ConfigurationForBaslerCLP` 設定為 `false`. Enter the full library path in `ClpSharedLibraryPath`, update the device list, and verify `LoadedClpSharedLibraryPath`.
虛擬裝置傳遞的是 Test Images 而非相機影像。	Applet 的影像產生器已啟用。請在虛擬裝置的遠端裝置節點中停用影像產生器。
`Interface` 或擷取卡初始化回報資源正在使用中。	另一個處理程序已佔用該擷取卡。每個擷取卡一次只能由一個處理程序進行初始化。針對
Camera Link，這包括獨立的 CLProtocol 用戶端（例如使用 clsersis.dll 的 pylon）。如需詳細資訊，請參閱同時安裝 pylon 與 Framegrabber SDK。
Producer 在初始化時回報已有另一個 Framegrabber SDK 版本正在執行。	Producer 從其他安裝載入了受保護的 Framegrabber SDK 模組（例如 fglib5.dll）。如需詳細資訊，請參閱同時安裝 pylon 與 Framegrabber SDK。
您無法存取 `Interface` 在偵測變更後的 consumer 設定。	未建立任何裝置，且 consumer 僅在至少存在一個裝置時顯示 `Interface` node map。請重設或編輯 .config 擷取卡的檔案。如需詳細資訊，請參閱 Applying and Persisting Changes.