PCO-FLIM Camera Control — 部署報告

本文件用於將此專案從原始開發環境部署到另一台 Windows 11 x64 機器。目標讀者為 AI agent 或具備基礎 Python 環境操作能力的工程師。含完整部署步驟、背景說明、腳本用途、組態參數解釋及疑難排解。

1. 專案概述

1.1 專案簡介

項目	說明
用途	控制 PCO FLIM (Fluorescence Lifetime Imaging Microscopy) 相機進行影像擷取
語言	Python 3.10
核心依賴	`pco` SDK (Excelitas PCO GmbH)、OpenCV、NumPy、Matplotlib
倉庫網址	`https://github.com/BOM303Lab/PCO-FLIM.git`
分支	`main`
需連接硬體	是（PCO FLIM 相機必須透過 USB/Camera Link/CLHS/GigE 連接）

1.2 核心依賴關係圖

本專案 (python_sample/*.py)
    ├── pco (>=2.0)          ─── PCO 相機 Python SDK
    │     └── sc2_cam.dll    ─── 底層 Windows x64 原生相機驅動
    ├── numpy (>=1.20)       ─── 陣列運算
    ├── opencv-python (>=4.5)─── 影像顯示、TIFF 讀寫
    └── matplotlib (>=3.5)   ─── 繪圖顯示（basic_acq.py / analysis 用）

1.3 採集流程總覽

                                   ┌─────────────────┐
                                   │ flim_config.json │
                                   │ (組態檔)         │
                                   └───────┬─────────┘
                                           │ 讀取
                                           ▼
  basic_flim_stack.py  ──>  pco.Camera()  ──>  設定曝光/觸發/ROI
                              │                  設定 FLIM 相位序列
                              │                  設定 FLIM 調變參數
                              │                  arm_camera()
                              │                  record(mode='sequence', 16 images)
                              │                  images()  ──> 16x uint16 arrays
                              │                  cv2.imwritemulti() ──> multi-page .tif
                              ▼
                        flim_data/*.tif
                              │
                              ▼
                     analysis_flim.py  ──>  強度歸一化圖表 (.png)

2. 硬體需求

2.1 必要硬體

項目	規格
相機	PCO FLIM 系列相機（具備 Tap A/B 感測器架構的光調變型相機）
連接介面	USB 3.0 / Camera Link (Me4 影像擷取卡) / CLHS (Camera Link HS) / GigE Vision
作業系統	Windows 11 x64 (原生 DLL 僅支援 x64)
其他	若使用 Kaya Vision Point 影像擷取卡，須設定環境變數 `KAYA_VISION_POINT_BIN_PATH`

2.2 背景說明

PCO FLIM 相機是時間-頻率域螢光壽命成像專用相機。它透過內建調變器以特定頻率（如 30 MHz）調變光訊號，並在感測器的 Tap A 和 Tap B 兩個通道上以不同相位進行取樣。一次 FLIM stack 採集通常包含 16 張影像：TAP A 在 8 個相位點的取樣 + TAP B 在 8 個相位點的取樣，交錯儲存於一個多頁 TIFF 檔案中。

若無相機硬體，本專案可完成虛擬環境建置和程式碼部屬，但執行擷取腳本時會報錯（相機 not found）。verify_environment.py 會以 [WARN] 而非 [FAIL] 回報此狀況。

3. 軟體需求

3.1 必要軟體

項目	最低版本	建議版本	備註
Python	3.10	3.10.x	64-bit 版
pip	隨 Python 安裝	最新	套件管理工具
Microsoft Visual C++ Redistributable	2015+	最新	`sc2_cam.dll` 等原生 DLL 的執行期需求

3.2 Python 套件依賴

詳見 requirements.txt：

套件	版本範圍	用途
`pco`	>=2.0	PCO 相機 SDK wrapper。安裝此套件時會一併部署 Windows x64 原生 DLL
`numpy`	>=1.20	陣列運算與資料處理
`opencv-python`	>=4.5	影像顯示 (cv2.imshow), 多頁 TIFF 寫入 (cv2.imwritemulti), TIFF 讀取 (cv2.imreadmulti)
`matplotlib`	>=3.5	靜態影像顯示 (basic_acq.py), 強度分析圖繪製 (analysis_flim.py)

3.3 關於 pco SDK 的背景說明

pco 套件是由 Excelitas PCO GmbH 維護的 Python wrapper，封裝了 PCO 相機的 C++ SDK。安裝時會包含以下關鍵 Windows x64 DLL：

DLL	用途
`sc2_cam.dll`	核心相機驅動—所有 API 呼叫的最終執行層
`sc2_cl_me4.dll`	Camera Link / Me4 影像擷取卡介面
`sc2_clhs.dll`	CLHS 介面
`sc2_genicam.dll`	GenICam 泛用傳輸層
`sc2_gige.dll`	GigE Vision 介面
`pco_recorder.dll`	影像錄製引擎
`pco_conv.dll`	色彩轉換引擎
`etc_xcite.dll`	Excelitas XCite 光源控制

這些 DLL 被安裝在 {site-packages}\pco\win_x64\，由 pco 套件的 loader.py 透過 ctypes.windll.LoadLibrary() 載入。

4. 部署步驟 (Step-by-Step)

以下指令皆在 PowerShell 5.1 或 命令提示字元 (cmd) 中執行。目標機器假設為一台 全新的 Windows 11 x64，尚未安裝 Python。

Step 1: 取得原始碼

# 方式 A: git clone (推薦)
git clone https://github.com/BOM303Lab/PCO-FLIM.git
Set-Location -LiteralPath "PCO-FLIM"

# 方式 B: 手動解壓
# 將 PCO-FLIM_camera_control.zip 解壓縮後，cd 到該目錄

Step 2: 安裝 Python 3.10

# 1. 從 https://www.python.org/downloads/ 下載 Python 3.10.x Windows x64 installer
# 2. 執行 installer，務必勾選 "Add Python to PATH"
# 3. 驗證安裝
python --version
# 預期輸出: Python 3.10.x

Step 3: 建立虛擬環境

# 在專案根目錄下執行
python -m venv venv

背景說明：虛擬環境 (venv) 將專案依賴隔離於系統 Python 之外，避免套件版本衝突。.gitignore 已排除 venv/，因此每台機器都需要重新建立。

Step 4: 啟用虛擬環境並安裝依賴

# 啟用 venv
.\venv\Scripts\Activate.ps1
# 若遇到執行原則限制:
#   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# 安裝依賴 (deployment/ 目錄已隨專案 clone 下來)
pip install -r deployment\requirements.txt

# 驗證安裝
pip list
# 應看到: pco, numpy, opencv-python, matplotlib 及它們的依賴

Step 5: 設定 flim_config.json

# 從 template 複製一份到 python_sample/ 目錄
Copy-Item deployment\flim_config.json.template python_sample\flim_config.json

然後用文字編輯器修改 python_sample/flim_config.json 中的參數以符合你的實驗需求。各參數含義詳見第 6 章。

Step 6: 驗證環境

# 執行環境驗證腳本 (需在 venv 啟用狀態下)
python deployment\scripts\verify_environment.py

預期結果：

Python 版本、套件、DLL、輸出目錄應顯示 [PASS]
「PCO 相機偵測」若相機未連接會顯示 [WARN]，屬於正常

Step 7: 執行測試

# 確認相機已開機並連接後：

# 測試 1: 單張擷取 (不需要 FLIM 組態)
python python_sample\basic_acq.py

# 測試 2: 即時預覽 (ESC 退出)
python python_sample\basic_live_cv.py

# 測試 3: FLIM stack 擷取 (需要 flim_config.json)
python python_sample\basic_flim_stack.py

5. 腳本使用指南

5.1 `basic_acq.py`

用途：最簡單的單張影像擷取。適合初次驗證相機連線是否正常。

執行指令：

python python_sample\basic_acq.py

預期行為：

連接到第一台可用的 PCO 相機
在 sequence 模式下拍攝 1 張影像
用 matplotlib 顯示該影像（包含灰階色條）

依賴：pco, numpy, matplotlib

5.2 `basic_live_cv.py`

用途：即時影像預覽，使用 ring buffer 模式（非阻塞式擷取）。

執行指令：

python python_sample\basic_live_cv.py

操作：按 ESC 鍵退出。

預設參數：

曝光時間: 0.250 秒
觸發模式: auto sequence
緩衝區: 4 張 ring buffer

依賴：pco, opencv-python, numpy

5.3 `basic_flim_stack.py` (核心腳本)

用途：執行完整 FLIM 影像堆疊 (stack) 擷取。這是本專案的主要功能腳本。

執行指令：

python python_sample\basic_flim_stack.py

執行流程：

從 python_sample/flim_config.json 讀取設定
套用標準相機參數（曝光、觸發、ROI）
套用 FLIM 相位序列設定（16 phases, singular, ascending, both taps）
套用 FLIM 調變設定（內部 30 MHz 方波/正弦波）
呼叫 arm_camera() 使 FLIM 參數生效
以 sequence 模式拍攝 16 張影像
擷取後將 FLIM 調變重設為 none/1MHz（避免雷射持續受調變）
以 cv2.imwritemulti 將 16 張影像存為多頁 16-bit TIFF

預期輸出：flim_data/{filename} (多頁 TIFF)

依賴：pco, opencv-python, numpy, json, os

5.4 `auto_acquire_fluorescein.py`

用途：自動化批次擷取。在迴圈中反覆修改 flim_config.json 的輸出檔名，每次呼叫 basic_flim_stack.py。

執行指令：

python python_sample\auto_acquire_fluorescein.py

說明：腳本目前設定為擷取 4 次（range(1, 5)），每次間隔 5 秒。可根據需求修改迴圈次數。

依賴：json, subprocess, os, sys

5.5 `analysis_flim.py`

用途：離線資料分析。讀取多頁 TIFF，執行 TAP A/B 分離、重新排序與歸一化強度分析。

執行指令：

# 使用前請先編輯腳本內的 FILENAME 變數 (第 9 行) 指向你的 TIFF 檔案
python python_sample\analysis_flim.py

分析流程：

cv2.imreadmulti 讀取多頁 TIFF
images[0::2] 取出 TAP A (偶數索引)
images[1::2] 取出 TAP B (奇數索引)
TAP A + TAP B 依序拼接為 reordered 序列
計算每幀平均強度，除以最大值進行歸一化
輸出 flim_data/intensity_plot.png

依賴：opencv-python, numpy, matplotlib, os

5.6 `inspect_pco.py`

用途：開發用工具。列出 pco.Camera 和 cam.sdk 物件的所有屬性和方法，以便探索可用 API。

執行指令：

python python_sample\inspect_pco.py

6. 執行期組態說明 (flim_config.json)

6.1 完整結構

{
    "standard_settings": { ... },
    "flim_phase_settings": { ... },
    "flim_modulation_settings": { ... },
    "output": { ... }
}

6.2 `standard_settings` 區段

鍵	型別	說明	常用值
`exposure time`	float	曝光時間 (秒)	`0.25` (250ms), `0.01` (10ms)
`roi`	[int]	感興趣區域 [x0,y0,x1,y1]	`[1,1,1008,1008]` (全幅)
`binning`	[int, int, str]	像素合併 [水平, 垂直, 模式]	`[1,1,"sum"]` (不合併)
`trigger`	str	觸發模式	`"auto sequence"`, `"software trigger"`, `"external"`

6.3 `flim_phase_settings` 區段

鍵	型別	說明	常用值
`phase_number`	str	相位數量	`"16 phases"`
`phase_symmetry`	str	相位對稱性	`"singular"` (單一序列), `"symmetrical"` (對稱序列)
`phase_order`	str	相位順序	`"ascending"` (遞增), `"descending"` (遞減)
`tap_select`	str	Tap 通道選擇	`"both"` (兩通道), `"tap_a"`, `"tap_b"`

背景說明：

phase_symmetry: "singular" 代表使用單一方向的相位序列 (0°, 22.5°, 45°, ...)
phase_order: "ascending" 代表相位從 0 度遞增
tap_select: "both" 代表 TAP A 和 TAP B 兩個通道輪流取樣
以 16 phases + both taps 為例，一個 stack 共 16 張影像：tap_a_phase0, tap_b_phase0, tap_a_phase1, tap_b_phase1, ... (交錯排列)

6.4 `flim_modulation_settings` 區段

鍵	型別	說明	常用值
`source`	str	調變訊號來源	`"intern"` (內部產生), `"extern"` (外部輸入)
`waveform`	str	調變波形	`"rectangular"` (方波), `"sinusoidal"` (正弦波), `"none"` (關閉)
`frequency`	int	調變頻率 (Hz)	`30000000` (30 MHz)

背景說明：

調變訊號用於驅動光源或感測器的調變
方波 (rectangular) 提供更銳利的時間閘控，但頻譜較寬
正弦波 (sinusoidal) 適合頻域 FLIM 分析
調變頻率需根據螢光染料的壽命範圍選擇（短壽命用高頻，長壽命用低頻）

6.5 `output` 區段

鍵	型別	說明	預設值
`directory`	str	輸出目錄路徑	`"flim_data"`
`filename`	str	輸出 TIFF 檔名	`"flim_stack.tif"`

7. 驗證清單

7.1 自動驗證

執行 deployment\scripts\verify_environment.py，所有項目應顯示 [PASS]：

檢查項目	通過條件
Python 版本	>= 3.10
pco 套件	import 成功
numpy 套件	import 成功
opencv-python (cv2)	import 成功
matplotlib 套件	import 成功
pco SDK DLL	`sc2_cam.dll` 存在於 site-packages
flim_config.json	存在且 JSON 格式合法、必要欄位齊全
輸出目錄可寫入	`flim_data/` 目錄可建立或已存在且可寫

7.2 手動驗證 (需連接相機)

測試	指令	預期結果
相機連線	`python python_sample\basic_acq.py`	顯示影像視窗
即時預覽	`python python_sample\basic_live_cv.py`	顯示即時畫面，FPS 正常更新
FLIM 擷取	`python python_sample\basic_flim_stack.py`	產生 `flim_data/*.tif` 多頁影像

8. 疑難排解

8.1 常見問題矩陣

錯誤訊息	可能原因	解決方案
`No module named 'pco'`	pco 套件未安裝	`pip install -r deployment\requirements.txt`
`ImportError: DLL load failed` (於 pco import)	缺少 VC++ Redistributable 或 Python 非 x64	安裝 VC++ Redistributable；確認 `python --version` 顯示 64-bit
`No camera found`	相機未開機或未連接	檢查相機電源指示燈、USB/Cable 連接線；執行 `inspect_pco.py` 確認 API 狀態
`sc2_cam.dll not found`	pco 套件安裝不完整	`pip uninstall pco -y; pip install pco`
`Failed to set exposure time`	相機不支援該曝光值	嘗試其他曝光時間 (如 0.01)；FLIM 相機部分參數受限
`Failed to set ROI`	FLIM 相機鎖定全解析度	正常現象，FLIM 相機通常固定 1008x1008 全幅，可忽略此錯誤
`cv2.imwritemulti` 失敗	opencv-python 版本過舊	`pip install --upgrade opencv-python`
PowerShell 無法執行 Activate.ps1	執行原則限制	`Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser`
相機連線成功但影像全黑	曝光不足或光源未開	增加 `exposure time`、確認光源已開啟，或將 `waveform` 設為 `none` 先測試
flim_config.json 找不到	範本未複製到 python_sample/	`Copy-Item deployment\flim_config.json.template python_sample\flim_config.json`

8.2 DLL 載入失敗的深入診斷

若 ImportError: DLL load failed 發生在 import pco，可進一步檢查：

# 檢查 Python 位元數
python -c "import struct; print(struct.calcsize('P') * 8)"
# 輸出應為 64

# 檢查 pco DLL 目錄
python -c "import pco, os; print(os.path.join(os.path.dirname(pco.__file__), 'win_x64'))"

# 列出該目錄下的 DLL
dir (python -c "import pco, os; print(os.path.join(os.path.dirname(pco.__file__), 'win_x64'))") -Filter *.dll

9. 專案目錄結構

PCO-FLIM_camera_control/          # 專案根目錄
├── .gitignore                    # Git 忽略規則 (venv/, flim_data/, __pycache__/)
├── readme.md                     # 英文簡介
├── PCOFLIM_parameters_intro.md   # PCO 參數完整說明 (繁體中文)
│
├── deployment/                   # ★ 部署包 (本次生成)
│   ├── DEPLOYMENT.md             #   部署報告 (本文件)
│   ├── requirements.txt          #   精簡依賴清單
│   ├── flim_config.json.template #   組態檔範本
│   └── scripts/
│       └── verify_environment.py #   環境驗證腳本
│
├── python_sample/                # 主要程式碼目錄
│   ├── basic_acq.py              #   單張影像擷取
│   ├── basic_live_cv.py          #   即時預覽 (OpenCV)
│   ├── basic_flim_stack.py       #   ★ FLIM stack 擷取 (核心)
│   ├── auto_acquire_fluorescein.py#  自動批量擷取
│   ├── analysis_flim.py          #   離線強度分析
│   ├── inspect_pco.py            #   API 探索工具
│   ├── flim_config.json          #   執行期組態 (需從 template 複製)
│   ├── flim_config-detail.json   #   完整版組態範例 (含 metadata/timestamp/noise 等)
│   └── flim_data/                #   輸出目錄 (gitignored)
│       ├── Light/                #     亮場實驗資料
│       └── Dark/                 #     暗場實驗資料
│
├── venv/                         # 虛擬環境 (gitignored, 每台機器獨立建立)
│   └── Lib/
│       └── site-packages/
│           └── pco/
│               └── win_x64/      #   PCO 原生 Windows x64 DLL
│                   ├── sc2_cam.dll
│                   ├── sc2_cl_me4.dll
│                   ├── pco_recorder.dll
│                   └── ...
│
└── src/                          # (空目錄，預留給未來 C/C++ 程式碼)

此部署報告由原始開發環境自動分析生成。專案原始倉庫: https://github.com/BOM303Lab/PCO-FLIM.git (branch: main) 若有問題或需要討論，請參考本文各章節的「背景說明」區塊。

FilesExpand file tree

DEPLOYMENT.md

Latest commit

History

DEPLOYMENT.md

File metadata and controls

PCO-FLIM Camera Control — 部署報告

目錄

1. 專案概述

1.1 專案簡介

1.2 核心依賴關係圖

1.3 採集流程總覽

2. 硬體需求

2.1 必要硬體

2.2 背景說明

3. 軟體需求

3.1 必要軟體

3.2 Python 套件依賴

3.3 關於 pco SDK 的背景說明

4. 部署步驟 (Step-by-Step)

Step 1: 取得原始碼

Step 2: 安裝 Python 3.10

Step 3: 建立虛擬環境

Step 4: 啟用虛擬環境並安裝依賴

Step 5: 設定 flim_config.json

Step 6: 驗證環境

Step 7: 執行測試

5. 腳本使用指南

5.1 basic_acq.py

5.2 basic_live_cv.py

5.3 basic_flim_stack.py (核心腳本)

5.4 auto_acquire_fluorescein.py

5.5 analysis_flim.py

5.6 inspect_pco.py

6. 執行期組態說明 (flim_config.json)

6.1 完整結構

6.2 standard_settings 區段

6.3 flim_phase_settings 區段

6.4 flim_modulation_settings 區段

6.5 output 區段

7. 驗證清單

7.1 自動驗證

7.2 手動驗證 (需連接相機)

8. 疑難排解

8.1 常見問題矩陣

8.2 DLL 載入失敗的深入診斷

9. 專案目錄結構

5.1 `basic_acq.py`

5.2 `basic_live_cv.py`

5.3 `basic_flim_stack.py` (核心腳本)

5.4 `auto_acquire_fluorescein.py`

5.5 `analysis_flim.py`

5.6 `inspect_pco.py`

6.2 `standard_settings` 區段

6.3 `flim_phase_settings` 區段

6.4 `flim_modulation_settings` 區段

6.5 `output` 區段