OpenMV MicroPython
image --- 机器视觉¶
image 模块是 OpenMV 机器视觉栈的核心。它提供了 Image 类——所有绘制、滤波、变换和特征提取例程所操作的内存像素缓冲区——以及这些例程所返回的相关结果对象（Blob、Line、Circle、Rect、QRCode、AprilTag、DataMatrix、BarCode、……），以及用于配置它们的辅助类（Threshold、Histogram、Statistics、HaarCascade、Similarity、Percentile、Displacement、ImageIO）。
获取图像¶
有四种方式可以将 Image 加载到 RAM 中：
从摄像头传感器实时捕获。 调用
csi.CSI.snapshot()将下一帧直接捕获到帧缓冲区中；返回的Image引用了该缓冲区。从文件加载。 将路径传递给
Image构造函数（image.Image("/sd/photo.jpg")）；支持的磁盘格式有 BMP、PPM/PGM、JPEG、PNG 以及 OpenMV 的ImageIO录制格式。从 ndarray 加载。 将一个 float32 类型的
(h, w)或(h, w, 3)ndarray传递给Image构造函数。像素值会从0.0 -- 255.0分别缩放为 GRAYSCALE 或 RGB565 图像。可用此方式将ml（或任何ulab流水线）的张量输出转换回可绘制的图像。空缓冲区。 以给定的尺寸和像素格式构造一个
Image（image.Image(320, 240, image.RGB565)），以便从零开始绘制，或用作图像运算的临时表面。
像素格式¶
每个 Image 都具有以下某一种像素格式；该选择需要在内存、处理开销以及可运行哪些算法之间进行权衡。在构造图像或配置摄像头传感器时，使用 BINARY、GRAYSCALE、RGB565、BAYER、YUV422、JPEG 或 PNG 作为 pixformat 参数：
BINARY (1 bpp) —— 每像素一位。最小的格式；由阈值化和形态学例程在内部使用，但很少直接从传感器捕获。
GRAYSCALE (8 bpp) —— 每像素一字节（YUV422 的 Y 通道）。对大多数机器视觉算法（AprilTag、边缘检测、光流）而言是最快的格式。
RGB565 (16 bpp) —— 每像素两字节，5 位红色 / 6 位绿色 / 5 位蓝色。默认的颜色格式。
BAYER (8 bpp) —— 直接来自传感器的原始拜耳模式颜色数据。适用于自定义去马赛克处理，或在按需去拜耳之前以更少的内存存储更多像素。
YUV422 (16 bpp) —— 4:2:2 色度二次采样的颜色，每像素两字节。当你想使用特定于色度的算法而又不必承担完整 RGB 开销时很有用。
JPEG / PNG —— 压缩缓冲区。最适合用于存储和网络传输。像素级操作需要先调用
Image.to_grayscale()或Image.to_rgb565()。
处理结果¶
Image 上的检测 / 特征提取方法会返回可供你迭代和组合的对象——一次 Image.find_blobs() 调用返回一个 Blob 列表，一次 Image.find_apriltags() 调用返回一个 AprilTag 列表，依此类推。每个结果类都暴露了该检测的几何属性（质心、边界框、面积、码值等），因此你可以直接对它们进行操作，或将它们传回绘制方法（Image.draw_rectangle()、Image.draw_string()、……）。
色彩空间辅助函数¶
该模块还提供了一些小型纯函数，用于在二值 / 灰度 / RGB / LAB / YUV 色彩空间之间转换单个像素值。当你需要在 Python 中转换阈值或调色板条目，然后再将其传入图像操作时，这些函数很有用——对于整幅图像的转换，请使用 Image 的 to_* 方法，它们比在循环中调用这些辅助函数要快得多。
类¶
- class Image -- 图像对象
- class ImageIO -- ImageIO 对象
- class HaarCascade -- 特征描述符
- class Similarity -- Similarity 对象
- class Histogram -- Histogram 对象
- class Percentile -- Percentile 对象
- class Threshold -- Threshold 对象
- class Statistics -- Statistics 对象
- class Blob -- Blob 对象
- class Line -- Line 对象
- class Circle -- Circle 对象
- class Rect -- Rectangle 对象
- class QRCode -- QRCode 对象
- class AprilTag -- AprilTag 对象
- class DataMatrix -- DataMatrix 对象
- class BarCode -- BarCode 对象
- class Displacement -- Displacement 对象
- class kptmatch -- 关键点匹配对象
函数¶
色彩空间转换辅助函数¶
下面的每个 X_to_Y 函数执行单个像素值的转换。它们都以 OpenMV 的规范范围取值/返回值：
二值 ——
int0 -- 1。灰度 ——
int0 -- 255。RGB —— 由 8 位整数组成的
(r, g, b)元组（每个为 0 -- 255）。LAB ——
(l, a, b)元组，其中L取值 0 -- 100，A/B取值 -128 -- 127。YUV ——
(y, u, v)元组，其中Y取值 0 -- 255，U/V取值 -128 -- 127。
对于整幅图像的转换，请使用 Image 的 to_* 方法，它们比在循环中调用这些辅助函数要快得多。
特征描述符¶
- image.HaarCascade(path: str, stages: int = -1) Cascade¶
加载一个 Haar 级联并返回一个
Cascade句柄，供Image.find_features()使用。path可以是：字面字符串
"frontalface"或"eye"，用于加载固件 ROM 中内置的两个级联之一，或者指向由 OpenMV 级联转换工具生成的自定义
.cascade二进制文件的文件系统路径。
stages选择在检测时评估多少个级联阶段。-1使用文件中存储的每一个阶段。减小该值可加快检测速度，但代价是产生更多误报。
- image.load_descriptor(path: str) kp_desc | lbp_desc¶
从
path处的文件加载一个描述符并返回它。文件内部的类型标签决定了重建哪个描述符类：ORB 关键点描述符 —— 由
Image.find_keypoints()生成后通过image.save_descriptor()保存。LBP 描述符 —— 由
Image.find_lbp()生成后通过image.save_descriptor()保存。
- image.save_descriptor(descriptor: kp_desc | lbp_desc, path: str) None¶
将
descriptor（一个 ORB 关键点或 LBP 描述符）以 OpenMV 描述符文件格式序列化到path处的文件。该文件之后可通过image.load_descriptor()重新加载。
- image.match_descriptor(descriptor0, descriptor1, threshold: int = 85, filter_outliers: bool = False) int | kptmatch¶
匹配两个相同类型的描述符。
对于两个 LBP 描述符 —— 返回它们之间的整数汉明距离（越低表示匹配越接近）。
对于两个 ORB 关键点描述符 —— 返回一个
kptmatch，描述匹配的关键点簇；如果没有匹配通过threshold，则返回None。
threshold（0 -- 100）设置 ORB 匹配在接受关键点对时的严格程度。较低的值通过拒绝弱的最近邻匹配来收紧匹配。filter_outliers在匹配的关键点集合上启用 RANSAC 风格的离群点剔除。当你预期两个视图之间存在单一刚性变换时使用它；当匹配的关键点跨越多个物体时禁用它。
色块几何辅助函数¶
这些辅助函数接收一个 Blob（由 Image.find_blobs() 返回）并按需计算额外的几何属性。它们位于模块作用域——而不在 Blob 上——因此基本的 find_blobs() 路径除非你主动调用，否则不会为它们付出开销。
- image.get_solidity(blob: blob) float¶
返回
blob的实度（blob.pixels / convex_hull_area）。浮点数，0 -- 1；1.0 表示色块完全填满了它的凸包。
常量¶
像素格式¶
将以下任意一项作为 pixformat 参数传递给 Image 构造函数或 csi.CSI.pixformat()。
- image.JPEG: int¶
压缩的 JPEG 缓冲区。像素级操作需要先调用
Image.to_grayscale()或Image.to_rgb565()。
- image.PNG: int¶
压缩的 PNG 缓冲区。像素级操作需要先调用
Image.to_grayscale()或Image.to_rgb565()。
颜色调色板¶
将以下任意一项传递给 Image.to_rainbow()、Image.to_ironbow()、Image.draw_image()（color_palette=）或 csi.CSI.color_palette()，以对灰度图像进行着色。
- image.PALETTE_DEPTH: int¶
深度图像调色板。仅在支持深度传感器的构建版本上可用（ToF 流水线——例如 OpenMV Cam AE3 或任何连接了 ToF Pmod 的摄像头）。
- image.PALETTE_EVT_DARK: int¶
用于在深色背景上可视化 GENX320 事件相机帧的调色板。将其传递给
csi.CSI.color_palette，可让 GENX320 驱动在直方图模式下输出着色的 RGB565 帧；或在对灰度事件图像着色时传递给Image.draw_image()的color_palette=。仅在支持 GENX320 的构建版本上可用（OpenMV Cam AE3 和 GENX320 Pmod）。
- image.PALETTE_EVT_LIGHT: int¶
用于在浅色背景上可视化 GENX320 事件相机帧的调色板。其分发方式和可用性与
PALETTE_EVT_DARK相同。
缩放模式¶
将以下任意一项作为 hint 参数传递给 Image.draw_image()、Image.scale() 或类似的缩放方法。
绘制 / draw_image 提示¶
将以下任意几项按位或（Bit-OR）组合在一起，作为 Image.draw_image() 的 hint 参数传递。
- image.EXTRACT_RGB_CHANNEL_FIRST: int¶
通过
Image.draw_image()提取某个 RGB 通道时，在缩放之前提取该通道。若无此提示，则在缩放之后提取该通道。
- image.APPLY_COLOR_PALETTE_FIRST: int¶
通过
Image.draw_image()应用颜色调色板时，在缩放之前应用该调色板。若无此提示，则在缩放之后应用该调色板。
JPEG 二次采样¶
在写入 JPEG 时，将以下任意一项作为 subsampling 参数传递给 Image.to_jpeg()、Image.compress() 或 Image.save()。
模板匹配¶
将以下任意一项作为 search 参数传递给 Image.find_template()。
边缘检测¶
将以下任意一项作为 algorithm 参数传递给 Image.find_edges()。
- image.EDGE_SIMPLE: int¶
阈值化高通滤波边缘检测器。比
EDGE_CANNY更快，但产生的边缘更粗、噪声更多。
ORB 角点检测器¶
将以下任意一项作为 corner_detector 参数传递给 Image.find_keypoints()。
- image.CORNER_FAST: int¶
FAST 角点检测器。比
CORNER_AGAST更快但精度较低。
- image.CORNER_AGAST: int¶
AGAST 角点检测器。比
CORNER_FAST更慢但产生的关键点更稳定。
AprilTag 家族¶
将以下任意组合按位或（Bit-OR）后作为 families 参数传递给 Image.find_apriltags()。每个家族在固件中由其各自的构建选项控制；不支持的家族在运行时是缺失的，而非始终为零。
条形码符号体系¶
Image.find_barcodes() 返回的条目在 BarCode.type 中所报告的值。
- image.PDF417: int¶
PDF417 二维堆叠条形码。该常量为完整起见而存在，但条形码解码器目前并未实现 PDF417 ——
Image.find_barcodes()不会返回此类型的检测结果。