買了這台相機，照著這份文件操作就行。
| 項目 | 說明 |
|---|---|
| PCO FLIM 相機本體 | 確認型號（如 pco.flim） |
| USB 3.0 傳輸線 | 藍色接頭（USB 3.0 Type-B 或 Type-C） |
| 電源供應器 | 12V DC 變壓器 |
| 電源線 | 依地區規格 |
| （選配）水冷管線 | 若搭配 pco.aquamatic III 水冷系統 |
Step 1: 電源供應器接上相機 DC IN，另一端插市電
Step 2: USB 3.0 線接上相機與電腦（用 USB 3.0 埠）
Step 3: （選配）水冷系統連接相機 IN/OUT 接頭
Step 4: 按相機電源開關
相機面板 LED 指示燈：
| LED 顏色 | 狀態 |
|---|---|
| 藍燈恆亮 | 電源正常，待命中 |
| 綠燈閃爍 | 正在擷取影像 |
| 黃燈 | 感測器冷卻中（開機初期正常） |
| 紅燈 | 錯誤（過熱或硬體故障） |
開機後等 5-10 分鐘，讓感測器冷卻到目標溫度（低於 5°C 比較好）。
# 開啟裝置管理員，確認以下項目：
# 展開「相機」或「影像裝置」→ 應看到 "pco.flim"
# 若出現黃色驚嘆號，表示驅動沒裝好
pip install pco會自動裝 Windows 驅動 DLL（sc2_cam.dll）。 若裝置管理員出現未辨識裝置，重執行：pip uninstall pco -y && pip install pco
| 項目 | 需求 |
|---|---|
| 作業系統 | Windows 10/11 64-bit（PCO SDK 只支援 x64） |
| Python | 3.10 或更新版本（64-bit） |
| VC++ Redistributable | 2015 以上（下載） |
| USB 埠 | USB 3.0（建議）或 USB 2.0 |
# 從 python.org 下載
# https://www.python.org/downloads/
# → 下載 Windows x64 installer
# → 務必勾選 "Add Python to PATH"
# → 安裝完成後驗證：
python --version
# 預期輸出: Python 3.10.x 或 3.11.x# 1. 進入專案目錄
cd PCO-FLIM_camera_control
# 2. 建立虛擬環境
python -m venv venv
# 3. 啟動虛擬環境
# Windows PowerShell:
.\venv\Scripts\Activate.ps1
# 若出現執行原則錯誤，先執行:
Set-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSigned
# Windows cmd:
# .\venv\Scripts\activate.bat
# 4. 安裝依賴套件
pip install -r requirements.txt
# 5. 安裝 pco_flim 套件（開發模式，讓 import 可以找到）
pip install -e .
# 6. （選配）TIFF 儲存支援
pip install tifffile# 測試 pco_flim 匯入（不需要相機）
python -c "from pco_flim import FLIMCamera, list_cameras; print('套件匯入成功')"
# 偵測相機（沒接相機時回傳 {}，這正常）
python -c "from pco_flim import list_cameras; print(list_cameras())"
# 輸出: {} ← 沒找到相機，但不影響學習參數設定帶你從開機到成功取得第一張 FLIM 影像。
# 1. 確定相機已開機（藍燈恆亮）
# 2. 等 5 分鐘讓感測器降溫
# 3. 執行溫度檢查：
python -c "
from pco_flim import FLIMCamera
with FLIMCamera() as cam:
info = cam.get_info()
temp = info.get('temperature', {})
if isinstance(temp, dict):
print(f'感測器溫度: {temp.get(\"sensor temperature\", \"N/A\")}°C')
print(f'機身溫度: {temp.get(\"camera temperature\", \"N/A\")}°C')
"
# 理想: 感測器 < 5°C先確認相機能正常拍攝，再進入 FLIM 模式：
python examples/01_basic_capture.py預期輸出：
==================================================
PCO FLIM 基本連線與快拍
==================================================
==================================================
相機型號：pco.flim
序號：XXXXX
介面：USB 3.0
...
==================================================
設定參數：曝光 10 ms, ROI 512×512
正在擷取影像...
影像資訊：
形狀 (H, W)：(512, 512)
資料型別：uint16
像素值範圍：[100, 45000]
平均值：8200.5
訊號強度在理想範圍內！
遇到問題，§8 故障排除 有解法。
確認快拍成功後，試試即時影像串流：
python examples/03_flim_live_view.py操作方式：
- 按
q退出預覽 - 按
s儲存當前幀為 TIFF
影像太暗，加大曝光時間；太亮（飽和），減少曝光時間或降低光源。
用標準 4 相位設定（最常用的起點）：
python examples/02_flim_4phase.py預期輸出（最後幾行）：
FLIM 4 相位擷取與分析完成！
此腳本會：
- 設定 20 MHz 調變頻率、正弦波
- 設定 4 相位 + singular + both
- 自動 ArmCamera
- 擷取 4 張相位影像
- 計算 Phasor G, S
- 計算螢光壽命 τ_φ, τ_m
- 繪製視覺化圖表
壽命值驗證：若用 Fluorescein 標準片（4.0 ns），測得 τ ≈ 3.5-4.5 ns 代表系統正常。
| 項目 | 完成？ |
|---|---|
| 相機可開機、LED 狀態正常 | ☐ |
list_cameras() 回傳非空 |
☐ |
basic_capture.py 顯示影像 |
☐ |
live_view.py 即時串流流暢 |
☐ |
flim_4phase.py 算出合理壽命 |
☐ |
| 感測器溫度低於 5°C | ☐ |
沒相機的電腦上也能先規劃參數。等接上相機後直接套用。
from pco_flim import describe_order, PHASE_4, TAP_BOTH
info = describe_order(PHASE_4, tap_select=TAP_BOTH)
print(f"SDK 輸出順序: {info['sdk_order_str']}")
print(f"重排後順序: {info['target_order_str']}")
print(f"影像張數: {info['n_images']}")完整對照表見 IMAGE_ORDER.md。
from pco_flim import (
PHASE_2, PHASE_4, PHASE_8, PHASE_16, # 相位數
TAP_BOTH, TAP_A, TAP_B, # Tap 選擇
SYMMETRY_SINGULAR, SYMMETRY_TWICE, # 對稱性
MOD_SOURCE_INTERNAL, MOD_SOURCE_EXTERNAL, # 調變來源
WAVEFORM_SINUSOIDAL, WAVEFORM_RECTANGULAR, # 波形
)
from pco_flim.presets import (
FLIM_4PHASE_DEFAULT,
FLIM_FRET,
FLIM_OXYGEN_SENSING,
FLIM_HIGH_SPEED_2PHASE,
FLIM_8PHASE_PRECISE,
)# my_flim_experiment.py — 可先寫好，有相機再執行
from pco_flim import FLIMCamera
# ============================================
# 實驗參數設定區（先在此規劃）
# ============================================
EXPOSURE = 0.01 # 曝光時間 [秒]
ROI = (1, 1, 512, 512) # ROI
FREQUENCY = 20e6 # 調變頻率 [Hz]
N_IMAGES = 4 # 4 phases × singular × both = 4 張
print("=== 實驗設定摘要 ===")
print(f" 曝光: {EXPOSURE*1000:.0f} ms")
print(f" 頻率: {FREQUENCY/1e6:.0f} MHz")
with FLIMCamera() as cam:
cam.print_info()
cam.set_exposure(EXPOSURE)
cam.set_roi(*ROI)
cam.set_flim_4phase(FREQUENCY)
images = cam.capture(N_IMAGES)
print(f"擷取完成: {images.shape}")你的實驗樣本是什麼？
│
▼
┌─────────────────────────────────────┐
│ 螢光壽命大約多少？ │
│ (查文獻或先測標準片) │
└──────────┬──────────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ 計算最佳調變頻率 │
│ f_opt = 1 / (2πτ) │
│ │
│ τ = 4 ns → 40 MHz │
│ τ = 10 ns → 16 MHz │
│ τ = 100 ns → 1.6 MHz │
└──────────┬──────────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ 選擇相位數 (影響影像張數) │
│ │
│ 快速掃描 → 2 相位（2 張） │
│ 標準 FLIM → 4 相位（4 張）推薦 │
│ 多成分分析 → 8 相位（8 張） │
│ 精細分布 → 16 相位（16 張） │
└──────────┬──────────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ 選擇曝光時間 │
│ (目標: 滿幅的 68-72%) │
│ 起點: 10 ms (4-phase FLIM) │
│ 太暗 → 增加曝光 │
│ 飽和 → 減少曝光或降低光源 │
└─────────────────────────────────────┘
| 應用場景 | 頻率 | 相位數 | 張數 | 曝光起點 | 備註 |
|---|---|---|---|---|---|
| 標準 FLIM 起點 | 20 MHz | 4 | 4 | 10 ms | 通用，先試這個 |
| FRET 測量 | 40 MHz | 4 | 8 (twice) | 10 ms | 短壽命，高頻 |
| 氧氣感測 | 5 MHz | 4 | 4 | 50 ms | 長壽命，低頻 |
| 快速掃描 | 20 MHz | 2 | 2 | 5 ms | 犧牲解析度換速度 |
| 多成分分析 | 20 MHz | 8 | 16 (twice) | 10 ms | 需要較多光子 |
| 校準 (Fluorescein) | 5-40 MHz | 4 | 4 | 10 ms | 掃描所有頻率 |
Step 1: 開機 → 等冷卻（5-10 分鐘）
Step 2: 設定曝光 → set_exposure(0.01)
Step 3: 設定調變 → set_flim_modulation(source=0, waveform=1, frequency=20e6)
Step 4: 設定相位 → set_flim_phase_sequence(phase_number=2, ...)
Step 5: ArmCamera → arm() ← 最關鍵
Step 6: 擷取影像 → capture(4)
Step 7: 計算 Phasor → compute_phasor(images)
Step 8: 計算壽命 → compute_lifetime_from_phasor(g, s, 20e6)
with FLIMCamera() as cam:
# 1. 一般參數（先設定，即時生效）
cam.set_exposure(0.01)
cam.set_roi(1, 1, 512, 512)
# 2. FLIM 調變參數（即時生效）
cam.set_flim_modulation(source=0, waveform=1, frequency=20e6)
# 3. FLIM 相位序列參數（需 ArmCamera）
cam.set_flim_phase_sequence(phase_number=2, symmetry=0, tap_select=0)
# 4. ArmCamera（必須！否則 FLIM 參數不生效）
cam.arm()
# 5. 擷取
images = cam.capture(4)pco.flim 用 FPGA 產生調變訊號與控制相位序列。改參數後：
你的 Python 程式 相機 FPGA
│ │
├─ set_flim_modulation() │ 參數暫存在暫存器
├─ set_flim_phase_sequence()│ 參數暫存在暫存器
│ │
├─ arm() ────────────────► │ 參數寫入 FPGA！
│ │
├─ capture(4) │ 用新參數拍攝
忘記 arm() → 相機用舊參數拍攝 → 拿到錯的順序或頻率 → 算出的壽命完全錯誤。
訊號強度控制：
- FLIM 的理想訊號強度為滿幅的 68-72%（約 44600-47200 counts for 16-bit）
- 低於此範圍 → 增加曝光時間或光源強度
- 高於此範圍（飽和）→ 減少曝光時間或降低光源強度
01_basic_capture.py會自動提示強度是否在理想範圍
溫度控制：
- 感測器溫度應低於 5°C 以獲得最佳 SNR
- 開機後等 5-10 分鐘讓 cooler 穩定
- 用
cam.check_temperature_stable()確認 - 若溫度持續過高：檢查風扇是否運轉、水冷系統是否正常
校準：
- 用已知螢光壽命的標準片（如 Fluorescein, τ ≈ 4.0 ns）
- 進行多頻率掃描（5-40 MHz）驗證系統一致性
- 見
examples/04_modulation_sweep.py
建議這樣命名，方便日後查找：
{樣本}_{條件}_{日期}_{流水號}.tif
例如：
fluorescein_ph7.4_20260610_001.tif
cells_fret_40MHz_20260611_001.tif
oxygen_sensor_5MHz_20260612_001.tif
方法一：用 tifffile 在 TIFF 中嵌入 metadata（見範例 5）：
import tifffile
tifffile.imwrite("output.tif", images, metadata={
"description": "FLIM 4-phase measurement",
"acquisition": {
"frequency_hz": 20e6,
"exposure_time_s": 0.01,
},
})方法二：將實驗參數另存為 JSON（與 TIFF 放同目錄）：
{
"sample": "Fluorescein pH 7.4",
"date": "2026-06-10",
"camera": "pco.flim",
"settings": {
"exposure_time_s": 0.01,
"frequency_hz": 20000000,
"phase_number": 4,
"symmetry": "singular",
"tap_select": "both"
},
"results": {
"tau_phi_mean_ns": 4.02,
"tau_mod_mean_ns": 4.15
}
}☐ 開啟相機電源
☐ 確認冷卻溫度 < 5°C
☐ 執行 basic_acq.py 確認相機正常
☐ 設定今日實驗的 flim_config.json
☐ （每週）執行 Fluorescein 標準片校準
| 頻率 | 目的 |
|---|---|
| 每次實驗前 | 快速確認（單張快拍 + 4-phase FLIM） |
| 每週 | Fluorescein 標準片頻率掃描（5-40 MHz） |
| 每月 | 完整校準（含 dark noise、flat field） |
本專案除了自行開發的 Python SDK，這台 PCO FLIM 相機也能透過 MicroManager（μManager） 搭配內建 PCO_Camera device adapter 操作。以下是兩者差異與已知問題。
| 面向 | Python SDK（本專案） | MicroManager 2.0 |
|---|---|---|
| 安裝難度 | pip install -e . 一行完成 |
需裝 μManager + PCO adapter + Java |
| 使用者介面 | 文字終端機 / Python 腳本 | 圖形化 GUI |
| FLIM 參數控制 | set_flim_4phase(20e6) 一行搞定 |
需透過 Device Properties 面板逐項設定 |
| 即時顯示 | 需自行寫 OpenCV（範例 03） | 內建 Live View |
| Phasor 分析 | 內建 compute_phasor() |
需額外裝 FLIMJ plugin（ImageJ） |
| 自動化批次 | 腳本迴圈即可 | 無內建批次 |
| 影像排列順序 | capture(reorder=True) 自動處理 |
需自行留意 SDK 原始順序 |
| Crash 穩定性 | 穩定（已驗證） | 有已知問題（見下方） |
以下問題經由分析本機 MicroManager 2.0 安裝（
mmgr_dal_PCO_Camera.dllv2.0.0.59，2021 年 7 月建置）與 JVM crash log 確認。
症狀： MicroManager 在初始化 PCO 相機時不定期 shutdown，無錯誤訊息直接消失。
根因：
mmgr_dal_PCO_Camera.dll v2.0.0.59 的 NULL pointer bug：
1. 呼叫 PCO_OpenCamera() 失敗（錯誤碼 35，通訊失敗）
2. 回傳值未檢查 → 拿到 NULL handle
3. 把 NULL handle 傳給下一支 API
4. EXCEPTION_ACCESS_VIOLATION → JVM 崩潰 → 整個程式 shutdown
Crash log 中明確記錄：
[ERR,Core:dev:pco_camera] Error in device "pco_camera":
Unable to communicate with the device. (35)
下一行就是 Access Violation。
為什麼 Python SDK 不會 crash？
# Python pco 套件在每支 C API 呼叫後都檢查回傳值
# 失敗時拋出 Exception，可以被 try/except 接住
# 而且 pip install pco 確保 SDK DLL 版本與 wrapper 完全匹配
try:
with pco.Camera() as cam: # 內部呼叫 PCO_OpenCamera()
pass
except Exception as e:
print(f"相機連線失敗: {e}") # 乾淨的錯誤訊息，不會 crash如果你仍然需要使用 MicroManager，建議：
- 先開相機電源，等待 30 秒，再開啟 MicroManager（避免觸發 NULL pointer bug）
- 不要在 Live 模式下調整參數（可能觸發 JNI race condition）
- 不要透過 Hardware Configuration Wizard 重新初始化已連接的裝置
- 如果需要穩定的 FLIM 控制，建議以本專案的 Python SDK 為主
兩種工具是互補關係，不是競爭關係：
| 用途 | 建議工具 |
|---|---|
| 第一次連線測試、Quick look | MicroManager（先開相機） |
| 例行標準化 FLIM 測量 | 本專案的 Python SDK |
| 自動化批次實驗（>10 個樣本） | 本專案的 Python SDK |
| 開發新的 FLIM 分析方法 | 本專案的 Python SDK |
| 需要圖形化介面的日常操作 | MicroManager（注意開機順序） |
Python SDK 完全穩定、可自動化、可客製化，建議作為主要的 FLIM 控制方案。 MicroManager 可留作輔助工具，但需注意其 device adapter 的已知問題。
pco.flim 的 Dual Tap 感測器在每次曝光中同時讀出兩個通道：
Double Image #1: A(0°) + B(180°)
Double Image #2: A(90°) + B(270°)
SDK 輸出: [A(0°), B(180°), A(90°), B(270°)] ← A/B 交錯
重排後: [A(0°), A(90°), B(180°), B(270°)] ← 升冪 (0°→360°)
from pco_flim import describe_order, PHASE_4, TAP_BOTH, SYMMETRY_TWICE
# 標準設定
info = describe_order(PHASE_4, tap_select=TAP_BOTH)
print(info["sdk_order_str"]) # [A@0°, B@180°, A@90°, B@270°]
print(info["target_order_str"]) # [A@0°, A@90°, B@180°, B@270°]
print(info["permutation"]) # [0, 2, 1, 3]
# Twice 模式（8 張）
info = describe_order(PHASE_4, SYMMETRY_TWICE, tap_select=TAP_BOTH)
print(info["sdk_order_str"]) # [A@0°, B@180°, A@90°, B@270°, A@180°, B@0°, ...]
print(info["target_order_str"]) # [A@0°, B@0°, A@90°, B@90°, ...]python examples/00_reorder_demo.py完整對照表（2/4/8/16-phase × 所有參數組合）見 IMAGE_ORDER.md。
| 問題 | 可能原因 | 解決方案 |
|---|---|---|
pip install pco 失敗 |
缺少 VC++ Redistributable | 安裝 VC++ Redistributable |
ImportError: DLL load failed |
Python 非 64-bit 或 DLL 損毀 | 確認 python -c "import struct; print(struct.calcsize('P')*8)" 輸出 64 |
No module named 'pco' |
pco 未安裝 | pip install pco |
| 問題 | 可能原因 | 解決方案 |
|---|---|---|
No camera found |
USB 未連接或驅動問題 | 檢查 USB 線、重新安裝 pco、檢查裝置管理員 |
| 相機在裝置管理員有驚嘆號 | 驅動未正確安裝 | pip uninstall pco -y && pip install pco |
list_cameras() 回傳 {} |
相機未開機 / USB 不通 | 確認電源 LED、換 USB 埠、換線 |
| 問題 | 可能原因 | 解決方案 |
|---|---|---|
| 影像全黑 | 曝光不足、光源未開 | 增加曝光時間、開啟光源、檢查快門 |
| 影像全白（飽和） | 曝光過度 | 減少曝光時間、降低光源強度、加 ND 濾鏡 |
| 影像有條紋 | 電源干擾 | 確認電源穩定、檢查 USB 線屏蔽 |
| 影像雜訊過高 | 溫度過高 | 等 cooler 降溫至 < 5°C |
| 感測器溫度降不下來 | 風扇故障 / 水冷問題 | 檢查風扇運轉、水冷幫浦、室溫 |
| 問題 | 可能原因 | 解決方案 |
|---|---|---|
| Phasor 值異常 | 順序錯誤 / 忘記 reorder | 確認 capture(reorder=True) |
ArmCamera 失敗 |
頻率超出硬體限制 | 確認頻率在 5 kHz~40 MHz |
| 壽命隨頻率變化 | 多成分樣本（正常！） | 用多頻率分析，非硬體問題 |
| 不同頻率壽命不一致 | 系統未校準 | 執行 Fluorescein 標準片掃描 |
若遇到 AttributeError（方法名稱不匹配），可用以下方式探索 SDK 實際 API：
import pco
with pco.Camera() as cam:
print("=== cam 屬性 ===")
print([a for a in dir(cam) if not a.startswith('_')])
print("\n=== cam.sdk 方法 ===")
print([a for a in dir(cam.sdk) if not a.startswith('_')])import logging
logging.basicConfig(level=logging.DEBUG)
# 或只針對 pco_flim
logging.getLogger("pco_flim").setLevel(logging.DEBUG)python deployment/scripts/verify_environment.py此腳本會檢查：Python 版本、套件安裝、DLL 存在、設定檔完整性。