v2.7.0

v2.7.0 將 sensor 的自動增益／自動曝光／白平衡 API 現代化，改採物理單位（dB／微秒），全面改寫相位相關的 find_displacement()（新增旋轉／縮放），並新增 get_similarity()（SSIM）、chrominvar() / illuminvar()、額外的影格緩衝區，以及一個 MQTT 函式庫。這是一個大型的破壞性版本 — 請閱讀下方的破壞性變更。

重點摘要

  • 現代化的 sensor API — set_auto_gain() / set_auto_exposure() / set_auto_whitebal() 現在使用 dB／微秒，並搭配對應的 get_gain_db() / get_exposure_us() / get_rgb_gain_db()。

  • 相位相關 — 改寫後的 find_displacement() 支援旋轉／縮放，並新增 find_rotscale() / linpolar() / logpolar()。

  • SSIM — image.get_similarity() 結構相似度。

  • 額外的影格緩衝區 — sensor.alloc_extra_fb() / dealloc_extra_fb()。

  • MQTT — 全新的 MQTT 函式庫。

  • 破壞性變更： sensor 的增益／曝光／白平衡 API、find_displacement() / FFT framesize、find_number()、WINC 韌體工具，以及 AprilTag 的 z_rotation() 皆有變動 — 詳見破壞性變更。

新功能

  • Sensor — 新增 sensor.get_gain_db()、sensor.get_exposure_us()、sensor.get_rgb_gain_db()、set_auto_gain() 上的 gain_db_ceiling 關鍵字、MT9V034 的 hmirror / vflip 支援，以及供額外 RAM 內影格緩衝區使用的 sensor.alloc_extra_fb() / sensor.dealloc_extra_fb()。

  • Image — 新增 remove_shadows()、min() / max()（影格差分）、get_similarity()（SSIM）並附上結構相似度範例、chrominvar() / illuminvar()、find_rotscale()、linpolar() / logpolar()、mean() / mode() / median() / midpoint() 自適應濾鏡上的 threshold／offset／invert 關鍵字、關鍵點物件上的 len() 與索引功能，以及關鍵點配對物件上的 .match() 存取器。

  • 函式庫／網路 — 新增 MQTT 函式庫（並附上 WiFi MQTT 範例），以及用於透過除錯 UART 燒錄 WINC 韌體的 network.WINC.MODE_BSP 模式。

  • 範例 — 新增低功耗的 deep_sleep.py / stop_mode.py、進階光流，以及線性／對數極座標範例指令碼；韌體現在會在開機時解析 uart.ini 以啟用 REPL UART。

其他變更與改進

  • get_regression() 新增了 area_threshold / pixels_threshold 關鍵字與更快速的穩健迴歸（用於循線／競速）；get_pixel() 現在支援 Bayer 影像；新增 STM32H7 前置作業（CMSIS 標頭檔／HAL／bootloader — H7 主機板尚不可用）；更新內建的 WINC1500 韌體（19.4.4 / 19.5.2）。

錯誤修正

影像處理：

  • 修正了 find_template() 鑽石搜尋的越界錯誤、logpolar / linpolar 損毀，以及 illuminvar() 在色彩值接近零時失控的問題。

感測器與系統：

  • 修正了自動增益控制的錯誤、在 snapshot() 時還原 MAIN_FB 大小（使不同解析度的 copy_to_fb、FB 縮放與光流池化得以再次運作）、WINC 的 gethostbyname 逾時、H7 bootloader 上 pydfu 的清除狀態，以及低功耗的停止／待命模式。

硬體與主機板支援

  • STM32H7 — 前置作業（CMSIS／HAL／bootloader）；OpenMV H7 主機板在此版本中尚不可用。

  • WINC1500 — 更新內建韌體。

破壞性 API 變更

v2.6.0 與 v2.7.0 之間使用者可見的 API 變更。範圍：modules/ 中的 Python C 模組與 scripts/libraries/ 中的 Python 函式庫。

每項變更都標註了其影響程度：

  • major — 影響大多數使用該功能的指令碼；你需要移植程式碼。

  • minor — 範圍狹窄的 API；只影響使用到它的指令碼。

  • behavior — API 相同但結果不同；請重新檢查已調校過的指令碼。

變更依影響程度依此順序分組。如果你只想移植自己的程式碼，請直接跳到結尾的 移植檢查清單。每個 commit 雜湊都連結到 GitHub 上的對應差異。

sensor.set_auto_gain() 改寫為 dB (major)

sensor.set_auto_gain() 不再接受整數的 value= 關鍵字，也不再回傳 True / False。請使用 sensor.set_auto_gain(False, gain_db=...)（浮點數 dB 值），透過新的 sensor.get_gain_db() 讀回該值，並以 try / except 包住呼叫，因為失敗現在會引發 ValueError。

Commits: b906c5f19

sensor.set_auto_exposure() 改寫為微秒 (major)

sensor.set_auto_exposure() 不再接受整數的 value= 關鍵字，也不再回傳 True / False。請使用 sensor.set_auto_exposure(False, exposure_us=...)，透過新的 sensor.get_exposure_us() 讀回該值，並處理失敗時引發的 ValueError。

Commits: 7be0a7a18

find_displacement() / FFT framesize 全面改寫 (major)

相位相關已全面改寫。image.find_displacement() 現在會回傳一個位移物件（具有 x_translation() / y_translation() — 原本為 x_offset / y_offset — 以及 rotation() / scale() 與新的 logpolar / fix_rotation_scale 關鍵字）；獨立的旋轉縮放物件已移除，並新增了 find_rotscale()。FFT framesize 常數已重新命名／移除：sensor.B40x30 已完全移除，而 sensor.B64x32 / B64x64 已重新命名為大寫的 sensor.B64X32 / B64X64（並新增 B128X64 / B128X128）。

Commits: c78f91b42, 213396d09

sensor.set_auto_whitebal() 改寫為 dB (minor)

sensor.set_auto_whitebal() 已將其整數的 value=[r, g, b] 關鍵字替換為 rgb_gain_db=[r, g, b]（浮點數 dB），現在回傳 None（失敗時引發 ValueError）而非 True / False。請使用新的 sensor.get_rgb_gain_db() 讀回增益值。

Commits: 30ecbdc4f

set_hmirror() / set_vflip() 回傳 None (minor)

sensor.set_hmirror() 與 sensor.set_vflip() 現在回傳 None，失敗時引發 ValueError，而非回傳 True / False 狀態。請移除任何依其回傳值分支判斷的程式碼。

Commits: aeb023804

WINC 韌體工具需要檔案路徑 (minor)

network.WINC 韌體工具已變更：wlan.fw_dump() / wlan.fw_update() 現在需要一個必填的韌體檔案路徑引數，且 WINC 會以燒錄模式開啟（network.WINC(mode=...)）。請更新無引數的呼叫以傳入路徑（例如 wlan.fw_update("/winc_19_5_2.bin")）。

Commits: fcc3b0b9c

image.find_number() 需要 28x28 的 ROI (behavior)

image.find_number()（LeNet）現在需要一個剛好為 28x28 且能容納於影像內的 ROI，否則會引發錯誤（而非在任意／全影像 ROI 上執行）。請傳入明確的 roi=(x, y, 28, 28)。

Commits: 4d09a13f3

AprilTag z_rotation() 正負號反轉 (behavior)

AprilTag 的 z_rotation()（及相關的 rotation()）現在採用右手座標慣例，因此回傳的角度相對於先前版本為相反數。依賴舊正負號的指令碼必須將該值反轉，或調整其角度運算。

Commits: 7673aaf74

移植檢查清單

若要順利移植至 v2.7.0，通常需要進行的工作如下：

  1. 將 set_auto_gain() 移植為 gain_db= + get_gain_db() 並處理 ValueError（自動增益改寫）。

  2. 將 set_auto_exposure() 移植為 exposure_us= + get_exposure_us()（自動曝光改寫）。

  3. 將 find_displacement() 更新為位移物件，並重新命名 FFT framesize 常數（find_displacement 改寫）。

  4. 將 set_auto_whitebal() 移植為 rgb_gain_db= + get_rgb_gain_db()（白平衡改寫），並停止檢查 set_hmirror() / set_vflip() 的回傳值（鏡像／翻轉變更）。

  5. 傳入韌體路徑給 WINC 的 fw_* 工具（WINC 工具變更）。

  6. 傳入 28x28 的 roi 給 find_number()（find_number 變更），並針對反轉的 z_rotation() 正負號調整 AprilTag 的角度運算（z_rotation 變更）。

其餘所有指令碼皆可不經修改正常執行。