v3.3.0

v3.3.0 是一個重大版本。它透過全新的 sensor.ioctl() 介面與色彩調色盤加入了完整的 FLIR Lepton 熱感相機支援、一個 tv SPI 視訊輸出模組、全域快門觸發模式、一大批新的 image 繪製/分析方法（gamma_corr()、draw_ellipse()、draw_edges()，以及許多色塊屬性），還有新的 ToF / 馬達 / linalg 函式庫。cpufreq API 經過重新設計，且 sensor.set_framesize() 現在會擲回例外——請閱讀下方的破壞性變更。

重點

  • FLIR Lepton——透過全新的 sensor.ioctl() 介面、色彩調色盤與 image.to_rainbow() 提供完整的熱感相機支援。

  • tv 模組——SPI TV / 複合視訊輸出。

  • 全域快門觸發模式——透過 sensor.ioctl() 進行 MT9V034 觸發擷取。

  • 影像處理——gamma_corr()、draw_ellipse()、draw_edges()、draw_image() 透明度混合，以及許多新的色塊屬性。

  • 新函式庫——VL53L1X ToF 距離、TB6612 馬達驅動程式、micro-linalg。

  • 破壞性變更： cpufreq API 經過重新設計，sensor.set_framesize() 現在會在失敗時擲回例外，sensor.alloc_extra_fb() 移除了 Bayer/JPEG，且 image.replace() 的位置引數有所調整——請參閱破壞性變更。

新功能

  • FLIR Lepton——新增了用於感測器專屬控制的 sensor.ioctl()，以及一整套 Lepton ioctl（輻射測量、更新率/解析度、執行命令、設定/取得屬性、以 °C 為單位的 FPA/AUX 溫度、測量模式/範圍、寬度/高度）、搭配 sensor.PALETTE_RAINBOW / PALETTE_IRONBOW 的 sensor.set_color_palette() / sensor.get_color_palette()、image.to_rainbow()，以及 Lepton 範例指令碼（27-Lepton）。

  • 觸發模式——為 MT9V034 全域快門觸發擷取新增 IOCTL_SET_TRIGGERED_MODE / IOCTL_GET_TRIGGERED_MODE，並附上高 FPS 與觸發模式範例。

  • tv 模組——新增 SPI TV / 複合視訊輸出綁定。

  • 影像處理——新增 image.gamma_corr()、image.draw_ellipse()、image.draw_edges()、draw_image() 透明度混合、clear() 上的 mask= 關鍵字，重新加入 mask_rectangle() / mask_circle() / mask_ellipse()，draw_string() / draw_text() 上的旋轉 / hmirror / vflip 關鍵字，replace() 上的 transpose 關鍵字（以及 assign / set 別名），copy() 的 x_scale / y_scale 以及 crop() / scale()，可由尺寸建立的 Image() 建構式、sensor.BINARY 像素格式、匯出的色彩空間轉換函式，以及許多新的色塊屬性（corners、perimeter、roundness、elongation、extent、compactness、solidity、convexity、enclosing_circle、enclosed_ellipse、旋轉）。

  • 函式庫——新增 vl53l1x ToF 距離感測器驅動程式、tb6612 馬達驅動程式（含直流馬達與步進馬達 Motor-Shield 範例），以及一個 micro-linalg 函式庫（ulinalg / umatrix）。

  • 將 FatFS 升級至 FF13C（支援 exFAT）。

其他變更與改進

  • 改進了預設 JPEG 品質（採用 low–high 的中間值，而非寫死的數值）；就地影像運算不再需要將影像重複作為第一個引數；draw_string() 接受非整數的縮放值。

錯誤修正

相機與感測器：

  • 修正了 Lepton 3.5 啟動當機（逾時 + 復原）與重設可靠性問題、MT9V034 在 set_pixformat() 之前呼叫 set_framesize() 的問題（呼叫順序不再有影響）、STM32H7 上的 MT9V034 WVGA、MT9V034 自動曝光範圍與影子暫存器更新，以及 H7 ADC 錯誤。

影像處理：

  • 修正了 find_apriltags() 中的無效記憶體存取、將縮放影像複製到主影格緩衝區時的 copy()、to_grayscale() / to_rgb565() 的影格緩衝區配置、關鍵點物件的 len()、JPEG MCU 邊界處理、binary() 閾值清單解析，以及 draw_keypoints() 接受關鍵點元組的問題。

系統：

  • 修正了跨 image / fir / lcd / tv / nn 方法的 fb_alloc mark/free 不平衡洩漏問題，讓 py_assert 在捕捉到例外時釋放影格緩衝區記憶體（#417），清除了 UART 溢位（ORE）旗標使溢位不再卡住 UART 讀取，修正了 RTC IRQ 處理常式，並修正了 Windows cascade_convert.py 工具。

硬體與開發板支援

  • FLIR Lepton 熱感相機。

  • TV shield——SPI TV / 複合視訊輸出。

  • 全域快門（MT9V034）觸發模式。

破壞性 API 變更

v3.2.0 與 v3.3.0 之間使用者可見的 API 破壞性變更。範圍：modules/ 中的 Python C 模組與 scripts/libraries/ 中的 Python 函式庫。

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

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

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

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

變更依影響程度依序分組。如果你只想移植程式碼，請跳至結尾的 遷移檢查清單。每個 commit 雜湊值都連結至其在 GitHub 上的 diff。

cpufreq API 重新設計 (major)

cpufreq 模組為了支援 H7 而重新設計。cpufreq.CPUFREQ_120MHZ / 144 / 168 / 192 / 216MHZ 常數與 cpufreq.get_frequency() 已被移除。cpufreq.set_frequency() 現在接受一個單純的 MHz 整數（例如 cpufreq.set_frequency(120)），並新增了 cpufreq.get_current_frequencies() / cpufreq.get_supported_frequencies()。

Commits: 6babf84a1

image.replace() 位置引數調整 (minor)

image.replace() 新增了一個 transpose 引數，使位置引數 mask 從第 4 個位置移至第 5 個位置。以位置方式傳遞 mask 的程式碼（例如 img.replace(src, hmirror, vflip, mask)）必須改用關鍵字形式 img.replace(src, mask=mask)。

Commits: dbe7bf059

sensor.alloc_extra_fb() 不再接受 Bayer/JPEG (minor)

sensor.alloc_extra_fb() 不再接受 sensor.BAYER 或 sensor.JPEG（現在也支援 sensor.BINARY）。以 Bayer 或 JPEG 格式配置額外影格緩衝區的程式碼必須改用 GRAYSCALE / RGB565（或以其他方式配置緩衝區）。

Commits: f9e6b3fe0

sensor.set_framesize() 在失敗時擲回例外 (behavior)

sensor.set_framesize() 現在會在影格尺寸不受支援時擲回 ValueError，而非回傳 False。檢查 False 回傳值的程式碼必須改為捕捉 ValueError 例外。

Commits: b0442633e

遷移檢查清單

若要乾淨地移植至 v3.3.0，典型的工作為：

  1. 將 cpufreq 程式碼移植至整數 MHz 的 set_frequency() 以及 get_current_frequencies() / get_supported_frequencies()（cpufreq 重新設計）。

  2. 以關鍵字方式將 mask 傳遞給 image.replace()（replace 變更）。

  3. 改以 GRAYSCALE / RGB565 而非 Bayer/JPEG 配置額外影格緩衝區（alloc_extra_fb 變更）。

  4. 在 sensor.set_framesize() 周圍捕捉 ValueError，而非檢查 False（set_framesize 變更）。

所有其他指令碼皆可不變執行。