v2.1.0

v2.1.0 是一个大规模的 API 现代化版本。它用 ORB 替换了 FREAK 关键点描述符，将 find_blobs() / 直方图 / 统计信息重构为基于对象的 API，重命名了 sensor 的自动曝光 / 增益 / 白平衡函数，新增了 QR 码检测和 OV7725 镜头校正，并完成了初步的 OpenMV Cam M7 开发板适配。许多 API 发生了变化——请阅读下方的破坏性变更。

亮点

  • ORB 关键点 —— FREAK 描述符被替换为 ORB（重构了 find_keypoints() / match_descriptor()）。

  • 对象 API —— find_blobs()、get_histogram()、get_statistics() 现在返回带命名访问器的对象。

  • QR 码 —— 新增 image.find_qrcodes() 检测。

  • OpenMV Cam M7 —— 初步的开发板支持。

  • 传感器 —— set_auto_whitebal() / set_auto_gain() / set_auto_exposure() （已重命名）和 set_lens_correction()。

  • 破坏性变更： 关键点 / 描述符、色块 / 直方图 / 统计信息、传感器自动函数以及其他若干 API 都发生了变化——请参阅破坏性变更。

新功能

  • OpenMV Cam M7 —— 新增初步的 OpenMV 3（M7）开发板支持。

  • QR 码 —— 新增 image.find_qrcodes()，附 qrcodes.py 示例。

  • ORB 关键点 —— 全新的 ORB 描述符系统：find_keypoints() 带有 corner_detector 参数（CORNER_FAST / CORNER_AGAST）、max_keypoints / scale_factor；match_descriptor() 带有 filter_outliers 关键字和旋转估计；以及关键点的保存 / 加载。

  • 对象 API —— image.get_histogram() / get_statistics() / get_percentile() 返回直方图 / 统计信息对象；find_blobs() 返回色块对象（rect() / cx() / cy() / code() / area() / pixels()），带有 area_threshold / pixels_threshold / merge / margin / invert 以及 x_stride / y_stride。

  • 传感器 —— 新增 sensor.set_lens_correction(enable, radi, coef) 用于 OV7725 镜头阴影校正，sensor.set_windowing() 现在也接受 (w, h) 元组（自动居中），以及 image.Image(..., copy_to_fb=True) / load_image(copy_to_fb=True)。

  • 新增了颜色跟踪、Arduino SPI/I2C 从机、关键点以及直方图 / 统计信息示例脚本。

其他变更与改进

  • IDE 现在可以中断正在运行的 main.py；find_blobs() / find_qrcodes() / get_statistics() 更快；ORB 使用 popcount 汉明距离；镜头校正占用更少的 RAM；一条 Linux udev 规则可阻止 ModemManager 抢占串口。

缺陷修复

摄像头与成像：

  • 修复了 M7 的 DMA 缓存清理 / 失效（损坏的帧）、每帧末尾多出的杂散行、JPEG 帧缓冲区溢出边界、compress() 失败时释放帧缓冲区、ORB 的准确性 / ROI / 空集处理，以及 load_image(copy_to_fb=True) 的几何问题。

系统：

  • 修复了 F7 的 ADC 支持、一个 OV7725 寄存器名称、引导加载程序 / USB 时序，在等待快照时使用了 WFI，并使 MJPEG 流式传输示例改为非阻塞且每个客户端带超时。

硬件与开发板支持

  • OpenMV Cam M7（OpenMV 3） —— 初步的开发板支持。

  • OV7725 —— 镜头校正（阴影）支持。

破坏性 API 变更

v2.0.0 与 v2.1.0 之间用户可见的 API 破坏性变更。范围：modules/ 中的 Python C 模块和 scripts/libraries/ 中的 Python 库。

每项变更都标注了其影响等级：

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

  • minor —— 影响范围窄的 API；仅影响使用过它的脚本。

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

变更按影响等级依次分组。如果你只想移植代码，可直接跳到末尾的 迁移清单。每个提交哈希都链接到其在 GitHub 上的差异。

FREAK 被 ORB 替换；描述符 API 重构 (major)

FREAK 关键点描述符被移除并替换为 ORB：image.FREAK 不再存在（请使用 image.ORB）。image.match_descriptor() / save_descriptor() / load_descriptor() 不再接受前导的描述符类型参数（它会从对象推断得出），match_descriptor() 现在返回一个 8 元素元组 (cx, cy, x, y, w, h, match_count, rotation)（最后一个元素是原始计数，而非百分比），且 draw_keypoints() 需要一个关键点对象，而非原始的 (x, y, angle) 列表。find_keypoints() 新增了 corner_detector / max_keypoints / scale_factor，且默认值有所改变。

提交： e2d0c4840、bba8e5a9e、6000684cb

传感器自动函数重命名 (major)

sensor.set_whitebal() / set_gain_ctrl() / set_exposure_ctrl() 被重命名为 sensor.set_auto_whitebal() / set_auto_gain() / set_auto_exposure()（旧名称已被移除）。每个函数都新增了一个可选的 value= 关键字，用于设置手动值而非自动。

提交： 1b22a2961

直方图 / 统计信息重构为对象 API (major)

直方图 / 统计信息接口被重构为基于对象的 image.get_histogram() / get_statistics() / get_percentile()，返回直方图 / 统计信息对象。旧的扁平直方图 / 统计信息结果以及 bin_count / l_bin_count / a_bin_count / b_bin_count 方法均被移除（请改用 len(histogram.bins()) 等）。

提交： 011108412、9f37c83de

find_features() 的 scale 重命名 (major)

image.find_features()（Haar）将其 scale= 关键字重命名为 scale_factor=。请将 find_features(cascade, scale=...) 调用更新为 scale_factor=...。

提交： 96e4f770c

find_blobs() 返回对象；find_markers() 被移除 (minor)

image.find_blobs() 现在返回带命名访问器的色块对象（为向后兼容，索引访问仍然有效），且 image.find_markers() 被移除——请改用 find_blobs(..., merge=True, margin=...)。不再支持高级颜色色块过滤回调。

提交： af15ec6eb

img.copy_to_fb() 被替换 (minor)

img.copy_to_fb() 方法被 image.Image / load_image() 上的 copy_to_fb= 关键字替换。请使用 image.Image(path, copy_to_fb=True) 将大图像直接加载到帧缓冲区。

提交： 1645ab94b

compress() 拒绝超出范围的质量 (behavior)

当 quality 超出 1–100 范围时，image.compress() / compressed() 现在会抛出错误，而非静默地将其钳制。请在调用前将 quality 钳制到 1–100。另外，OpenMV 3 的 JPEG 缓冲区从 64 KB 减小到 23000 字节，因此大帧现在可能会引发内存不足——请降低 JPEG 质量或帧尺寸。

提交： 9efd7474a、9a7c3defc

lens_corr() 的缩放现已生效 (behavior)

image.lens_corr() 现在会实际应用其 zoom 参数（之前虽会解析但无效），因此对于传入非默认缩放值的脚本，输出会有所不同。请重新检查 lens_corr() 的调优。

提交： d6b49adef

迁移清单

要顺利移植到 v2.1.0，通常需要做的工作是：

  1. 将 image.FREAK 替换为 image.ORB，去除描述符类型参数，并将 match_descriptor() 的元组解包 / draw_keypoints() 更新为关键点对象（ORB 重构）。

  2. 将 sensor.set_whitebal() / set_gain_ctrl() / set_exposure_ctrl() 重命名为 set_auto_* 形式（自动函数重命名）。

  3. 将直方图 / 统计信息代码改用对象方法（直方图 / 统计信息重构）。

  4. 将 find_features() 的 scale= 重命名为 scale_factor=（find_features 重命名）。

  5. 使用色块对象访问器，并将 find_markers() 替换为 find_blobs(merge=True, ...)（find_blobs 变更）；将 img.copy_to_fb() 替换为 copy_to_fb= 关键字（copy_to_fb 变更）。

  6. 将 compress() 的质量钳制到 1–100，并在 OpenMV 3 上重新检查 JPEG 尺寸（compress 变更）；重新调优 lens_corr() 的缩放（lens_corr 变更）。

其余所有脚本均可原样运行。