快速入門#

本主題透過簡單的工作流程向您展示 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)

讓我們將此範例拆解為 jednotlivá 步驟：

建立與管理相機
```
with pylon.InstantCamera(pylon.FirstFound) as camera:
```
這一行執行了兩個重要的動作：
- 它選取 第一個可用的相機，使用傳輸層原廠 (transport layer factory) 建立 pylon 裝置物件，並將其包裝在 InstantCamera 物件中以方便使用。
- 要 with 確保即使發生錯誤，也能自動釋放資源並正確關閉相機。
開始擷取
```
camera.StartGrabbingMax(1)
```
如果相機尚未開啟，此動作會將其開啟、啟動擷取引擎，並指示相機執行以下操作：
- 精確擷取 一個畫面。
- 隨後停止擷取。
這非常適合用於測試，因為它能避免無限迴圈。

也可以透過呼叫 Open 事先開啟相機。
```
camera.Open()
```
開啟會建立連線並使相機準備好執行以下任務：
- 設定參數
- 開始擷取
擷取抓取結果
```
with camera.RetrieveResult(5000) as grab_result:
```
此呼叫會進行阻斷，直到發生以下任一事件：
- 影格可用。
  或
- 達到逾時時間 (5000 ms)。
在內部，您是從緩衝區佇列 (buffer queue) 中擷取影像。
驗證擷取結果
```
if grab_result.GrabSucceeded():
```
即使傳回了擷取結果，擷取作業仍可能失敗（例如傳輸錯誤）。在使用資料之前，請務必檢查是否成功。
建立像素資料的複本（選用）

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

離開 with 區塊後，來自擷取結果的緩衝區將會失效，因為 grab_result 已被釋放。若要在 with 區塊外部使用像素資料，您需要建立其複本。您可以使用 Array 函式來建立像素資料的複本。
```
image = grab_result.Array
```
使用影像
```
print(image.shape)
```
這確認了以下事項：
- 影像存在。
- 資料具有有效的形狀。

心智模型#

此視覺化圖解說明瞭內部的運作方式。

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 以確保安全的資源處理。

一旦您理解了這個模式，即可在此基礎上編寫程式碼來執行以下任務：

建立連續擷取迴圈
設定觸發擷取
設計多相機設定