v2.7.0

v2.7.0 将 sensor 的自动增益 / 自动曝光 / 白平衡 API 现代化，改用物理单位（dB / 微秒），全面改造了相位相关的 find_displacement()（新增旋转 / 缩放），并新增了 get_similarity()（SSIM）、chrominvar() / illuminvar()、额外的 framebuffer 以及一个 MQTT 库。这是一个包含大量破坏性变更的版本 —— 请阅读下方的破坏性变更。

亮点

  • 现代化传感器 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() 结构相似度。

  • 额外的 framebuffer —— sensor.alloc_extra_fb() / dealloc_extra_fb()。

  • MQTT —— 全新的 MQTT 库。

  • 破坏性变更： 传感器增益 / 曝光 / 白平衡 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 支持，以及用于额外内存 framebuffer 的 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 关键字，在 keypoints 对象上新增 len() / 索引，并在 keypoint 匹配对象上新增 .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 / 引导加载程序 —— H7 主板尚不可用）；更新了捆绑的 WINC1500 固件（19.4.4 / 19.5.2）。

错误修复

成像：

  • 修复了 find_template() 菱形搜索越界的错误、logpolar / linpolar 损坏问题，以及 illuminvar() 在颜色值接近零时失控的问题。

传感器与系统：

  • 修复了自动增益控制的错误，恢复了 snapshot() 时的 MAIN_FB 大小（使得不同分辨率下的 copy_to_fb、FB 调整大小以及光流池化重新可用），修复了 WINC 的 gethostbyname 超时、H7 引导加载程序上 pydfu 的 clear-status，以及低功耗 stop/standby 模式。

硬件与主板支持

  • STM32H7 —— 前期准备工作（CMSIS / HAL / 引导加载程序）；OpenMV H7 主板在本版本中尚不可用。

  • WINC1500 —— 更新了捆绑固件。

破坏性 API 变更

v2.6.0 与 v2.7.0 之间对用户可见的 API 破坏性变更。范围：modules/ 中的 Python C 模块以及 scripts/libraries/ 中的 Python 库。

每项变更都标注了其影响程度：

  • major —— 影响大多数使用该功能的脚本；你需要移植代码。

  • minor —— 涉及面窄的 API；仅影响使用了它的脚本。

  • behavior —— API 相同但结果不同；请重新检查经过调优的脚本。

变更按影响程度依此顺序分组。如果你只想移植代码，可直接跳到结尾的 迁移清单。每个提交哈希都链接到它在 GitHub 上的 diff。

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。

提交： 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。

提交： 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）。

提交： 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() 读回增益。

提交： 30ecbdc4f

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

sensor.set_hmirror() 和 sensor.set_vflip() 现在返回 None，失败时抛出 ValueError，而不再返回 True / False 状态。请移除任何根据其返回值进行分支判断的代码。

提交： aeb023804

WINC 固件工具需要文件路径 (minor)

network.WINC 固件工具有变化：wlan.fw_dump() / wlan.fw_update() 现在需要一个必填的固件文件路径参数，并且 WINC 以烧录模式打开（network.WINC(mode=...)）。请更新无参数的调用以传入路径（例如 wlan.fw_update("/winc_19_5_2.bin")）。

提交： fcc3b0b9c

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

image.find_number()（LeNet）现在需要一个恰好为 28x28 且位于图像内部的 ROI，否则会抛出错误（而不是在任意 / 全图 ROI 上运行）。请传入显式的 roi=(x, y, 28, 28)。

提交： 4d09a13f3

AprilTag 的 z_rotation() 符号翻转 (behavior)

AprilTag 的 z_rotation()（以及相关的 rotation()）现在使用右手坐标约定，因此返回的角度相对于此前版本被取反。依赖旧符号的脚本必须对该值取反或调整其角度运算。

提交： 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. 向 find_number() 传入 28x28 的 roi（find_number 变更），并针对翻转后的 z_rotation() 符号调整 AprilTag 的角度运算（z_rotation 变更）。

所有其他脚本无需修改即可运行。