跳至內容
測試伺服器
開發伺服器

快速入門#

本主題透過一個簡單的工作流程向您展示 pypylon 的第一步。

其目的不僅在於展示能運作的程式碼，更在於讓您了解如何在更複雜的場景中重複使用和調整範例程式碼。

逐步範例#

最簡單的 pypylon 影像擷取包含以下步驟：

  • 尋找相機
  • 開啟相機
  • 開始影像擷取
  • 檢索影像
  • 處理影像

以下範例示範了這些步驟。它還具有以下額外的好處：

  • 它可讓您驗證安裝是否正常運作。
  • 您可以測試相機連線能力。
  • 它有助於您了解擷取生命週期。

範例：

from pypylon import pylon

with pylon.InstantCamera(pylon.FirstFound) as camera:
    camera.StartGrabbingMax(1)

    with camera.RetrieveResult(5000) as grab_result:
        if grab_result.GrabSucceeded():
            image = grab_result.Array
            print(image.shape)

讓我們將此範例拆解為個別步驟：

  1. 建立與管理相機

    with pylon.InstantCamera(pylon.FirstFound) as camera:

    這行程式碼執行了兩個重要的動作：

    • 它選取 第一個可用的相機，使用傳輸層原廠模式（Transport Layer Factory）建立 pylon 裝置物件，並將其包裝在 InstantCamera 物件中以方便使用。
    • 使用 with 確保即使發生錯誤，也能自動釋放資源並正確關閉相機。

  2. 開始擷取

    camera.StartGrabbingMax(1)

    如果相機尚未開啟，這會開啟相機，啟動擷取引擎，並指示相機執行以下動作：

    • 剛好擷取 一個畫面。
    • 隨後停止擷取。

    這非常適合進行測試，因為它可以避免無限迴圈。

    也可以事先透過呼叫 Open 來開啟相機。

    camera.Open()

    開啟動作會建立連線並讓相機準備好執行以下任務：

    • 設定參數
    • 開始擷取

  3. 擷取擷取結果

    with camera.RetrieveResult(5000) as grab_result:

    此呼叫將會封鎖，直到發生以下其中一個事件：

    • 畫面可用。
      或
    • 已達到逾時時間 (5000 ms)。

    在內部，您是從buffer queue中提取影像。

  4. 驗證擷取

    if grab_result.GrabSucceeded():

    即使傳回了擷取結果，擷取作業也可能失敗（例如傳輸錯誤）。在使用資料之前，務必檢查是否成功。

  5. 建立像素資料的複本（選用）

    擷取結果會使用 buffer pool 中的 buffer。當您存取 grab_result.Array時，您會取得擷取結果 buffer 資料的複本。或者，您也可以使用 GetMemoryView() 或 GetArrayZeroCopy() 來存取資料而不進行複製。

    來自擷取結果的 buffer 在離開 with 區塊後就會失效，因為 grab_result 已被釋放。若要在 with 區塊外部使用像素資料，您需要建立其複本。您可以使用 Array 函式來建立像素資料的複本。

    image = grab_result.Array

  6. 使用影像

    print(image.shape)

    這確認了以下事項：

    • 影像存在。
    • 資料具有有效的形狀。

為互動式 GigE 工作階段啟用 ConnectionGuard#

當您從偵錯工具開啟 GigE 相機時，pylon 會自動開啟 ConnectionGuardEnable 在 Open()。這會執行兩項操作：

  • 它會將心跳逾時時間增加至 60 分鐘，以便相機不會意外重新啟動。
  • 如果您的程式突然停止，它會平順地關閉連線。

如果您想要明確設定它，請在開啟相機之前進行設定：

from pypylon import pylon

with pylon.InstantCamera() as camera:
    camera.Attach(pylon.FirstFound)
    camera.TLNodeMap.ConnectionGuardEnable.Value = True
    camera.Open()

當您希望在偵錯工具工作階段之外獲得相同的行為時，這非常有用。

Mental Model#

此視覺化圖表說明瞭內部發生的情況。

Camera (hardware)
      ↓
pylon driver + buffers
      ↓
Transport layer (USB/GigE)
      ↓
RetrieveResult()
      ↓
NumPy array (your application)

核心概念：

  • 相機以非同步方式執行（產生畫面）。
  • 您的 Python 程式碼以同步方式消耗畫面。

緩衝區位於兩者之間，並將這兩個世界（相機與應用程式）解耦。

重點整理#

  • 務必檢查 GrabSucceeded().
  • 在離開結果範圍或釋放擷取結果之前，務必複製影像資料，例如使用 Array 函式搭配使用。
  • 使用 StartGrabbingMax(1) 進行簡單的測試。或者，您可以使用 GrabOne(5000).
    StartGrabbingMax(1) 剛好擷取一張影像。 GrabOne(5000) 擷取一張影像，但在 5000 µs 後逾時。
  • 使用 with 以確保安全的資源處理。

一旦您理解了此模式，便可以此為基礎來編寫用於以下任務的程式碼：