快速入門#

本主題將透過一個簡單的工作流程，向您介紹 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)

讓我們將這個範例拆解成各個步驟：

建立與管理攝影機
```
with pylon.InstantCamera(pylon.FirstFound) as camera:
```
這行代碼有兩項重要功能：
- 它選取了 首款上市的相機, 使用傳輸層工廠來建立一個 pylon 裝置物件，並將其封裝在一個 InstantCamera 物件，以便於使用。
- 要 with 確保即使發生錯誤，資源仍會自動釋放，且攝影機也能正常關閉。
開始擷取
```
camera.StartGrabbingMax(1)
```
此操作會開啟攝影機（若尚未開啟），啟動擷取引擎，並指示攝影機執行以下操作：
- 擷取恰好一個畫面。
- 之後停止收購。
這對於測試來說是理想的，因為它能避免陷入無限迴圈。

此外，也可透過呼叫 Open 函式，預先開啟相機。
```
camera.Open()
```
「開啟」會建立連線，並讓相機做好準備以執行後續任務：
- 設定參數
- 開始擷取
擷取抓取結果
```
with camera.RetrieveResult(5000) as grab_result:
```
此呼叫會一直阻塞，直到發生以下任一事件為止：
- 現有畫框可供選用。請寄信至
  或
- 已達到超時（5000 毫秒）。
在內部，您是從緩衝區佇列中擷取一張圖片。
驗證抓取結果
```
if grab_result.GrabSucceeded():
```
即使系統回傳了擷取結果，擷取操作仍可能已失敗（例如：傳輸錯誤）。在使用資料之前，務必先確認操作是否成功。
建立像素資料的副本（可選）

Grab 的結果會使用來自緩衝區池的緩衝區。當您存取 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 以確保資源處理的安全性。

一旦理解了這個模式，您就可以以此為基礎，撰寫程式碼來完成以下任務：