class Image -- 图像对象¶

Image 是 image 模块的核心数据类型——它是一个内存中的像素缓冲区，所有的绘制例程、所有的滤波器、所有的几何变换以及所有的特征提取例程都在它之上运行。从 csi.CSI.snapshot() 输出的每一帧都是 Image；从磁盘加载、从 JPEG 或 PNG 解码、从 numpy 风格的 ndarray 分配、或构造为空白绘制画布的每一帧也同样如此。

一个 Image 由三个数值描述——width、height 和 pixformat——外加一个连续的像素缓冲区。像素格式既决定了内存中的布局，也决定了哪些操作可用：

BINARY（1 bpp）——每像素 1 比特；用于形态学操作和阈值处理。
GRAYSCALE（8 bpp）——每像素 1 字节；是大多数计算机视觉操作（AprilTag、边缘、ORB、光流）的规范格式。
RGB565（16 bpp）——每像素 2 字节（5R/6G/5B）；默认的颜色格式。
BAYER（8 bpp）——直接来自传感器的原始 Bayer 马赛克数据。大多数计算机视觉方法不能在 Bayer 图像上使用；请先去马赛克转换为 GRAYSCALE / RGB565。
YUV422（16 bpp）——4:2:2 色度二次采样的颜色格式，每像素两字节。只有部分方法可直接在 YUV422 上工作。
JPEG / PNG——压缩缓冲区。像素级操作需要先调用 to_grayscale() 或 to_rgb565()。

Image 对象的来源¶

有四种方式可以获得一个 Image：

来自摄像头帧缓冲区——csi.CSI().snapshot() 返回下一帧捕获的图像。返回的对象是对摄像头帧缓冲区内存的一个轻量封装，因此对它进行的任何绘制 / 滤波操作都会改变发送到 IDE 预览和显示器的内容。
来自文件——向 Image 构造函数传入一个路径字符串。BMP、PGM、PPM、JPEG 和 PNG 会被直接解码到 RAM 中（如果 copy_to_fb=True 则解码到摄像头帧缓冲区中）。
来自 ndarray——传入一个 (h, w) 或 (h, w, 3) 的 float32 数组。像素值会从 0.0 -- 255.0 分别缩放为 GRAYSCALE 或 RGB565。
空白图像——传入 (width, height, pixformat) 以分配一个填充全零的绘制表面。对于压缩像素格式（JPEG / PNG）需要一个 buffer= 参数，用于保存压缩字节流。

典型的捕获-处理-显示循环¶

import csi
import image

sensor = csi.CSI()
sensor.reset()
sensor.pixformat(csi.RGB565)
sensor.framesize(csi.QVGA)

while True:
    img = sensor.snapshot()                    # capture
    for blob in img.find_blobs([(30, 100, 15, 127, 15, 127)]):  # process
        img.draw_rectangle(blob.rect)          # annotate
    # img is shown automatically in the IDE preview and on any
    # attached display.

索引、长度、迭代以及类字节访问¶

索引——img[i] 读取像素 i（按行优先线性排列）。img[i] = value 写入它。灰度 / Bayer 像素是 8 位整数，RGB565 / YUV422 像素是 16 位打包整数，二值像素为 0 / 1。对于 JPEG / PNG 图像，索引空间是压缩字节流，而非像素。
长度——len(img) 对于未压缩格式返回像素数，对于压缩格式返回字节数。
迭代——for px in img: ... 以与 [] 索引相同的顺序遍历像素数组。
类字节访问——Image 实现了读缓冲区协议，因此你可以将它直接传给任何接受 bytes / bytearray 的对象（例如 uart.write(img)、socket.send(img)、hashlib.sha256(img)）。如需获得可读写视图，请改用 bytearray()。

Hint 标志¶

许多 Image 方法接受一个 hint 参数，它是以下标志的逻辑或：

image.AREA：在缩小图像时使用区域缩放，而不是默认的最近邻缩放。

image.BILINEAR：使用双线性缩放，而不是默认的最近邻缩放。

image.BICUBIC：使用双三次缩放，而不是默认的最近邻缩放。

image.CENTER：将绘制的图像在显示器上居中。此操作在缩放之后应用。

image.HMIRROR：水平镜像图像。

image.VFLIP：垂直翻转图像。

image.TRANSPOSE：转置图像（交换 x/y）。

image.EXTRACT_RGB_CHANNEL_FIRST：在缩放之前进行 rgb_channel 提取。

image.APPLY_COLOR_PALETTE_FIRST：在缩放之前应用颜色调色板。

image.SCALE_ASPECT_KEEP：缩放绘制的图像以适应显示器内部。

image.SCALE_ASPECT_EXPAND：缩放绘制的图像以填满显示器（会导致裁剪）。

image.SCALE_ASPECT_IGNORE：缩放绘制的图像以填满显示器（会导致拉伸）。

image.ROTATE_90：将图像旋转 90 度（即 VFLIP | TRANSPOSE）。

image.ROTATE_180：将图像旋转 180 度（即 HMIRROR | VFLIP）。

image.ROTATE_270：将图像旋转 270 度（即 HMIRROR | TRANSPOSE）。

image.BLACK_BACKGROUND：假定被绘制的背景图像是黑色，以加速混合。仅 Image.draw_image() 和 Image.get_similarity() 支持。

如果 arg 是字符串，则会从 arg 路径处的文件创建一个新的图像对象。支持从磁盘加载 bmp/pgm/ppm/jpg/jpeg/png 图像文件。如果 copy_to_fb 为真，则将图像复制到帧缓冲区，而不是在堆上分配。

如果 arg 是一个 ndarray，则会从该 ndarray 创建一个新的图像对象。形状为 (w, h) 的 ndarray 对象被视为灰度图像，(w, h, 3) 的被视为 RGB565 图像。目前仅支持 float32 浮点型 ndarrays。以这种方式创建图像时，如果传入 buffer 参数，它将被用于存储图像数据，而不是在堆上分配空间。如果 copy_to_fb 为真，则将图像复制到帧缓冲区，而不是在堆上分配或使用 buffer。

如果 arg 是一个 int，则它被视为新图像的宽度，并且后面必须跟一个 height 值和一个 format 值来创建一个新的空白图像对象。format 可以是任意图像像素格式值，例如 image.GRAYSCALE。图像将被初始化为全零。注意，对于压缩图像格式需要提供 buffer 值。buffer 被视为以此方式创建图像的图像数据来源。如果与 copy_to_fb 一起使用，则 buffer 中的数据会被复制到帧缓冲区。如果你想从一个 JPEG bytes() 或 bytearray() 对象创建 JPEG 图像，可以为 JPEG 传入 width、height、image.JPEG，并将 buffer 设置为 JPEG 字节流来创建 JPEG 图像。

图像支持 "[]" 表示法。使用 image[index] = 8/16-bit value 来给图像像素赋值，或使用 image[index] 来获取图像像素，对于灰度/bayer 图像它将是 8 位值，对于 RGB565/YUV 图像它将是 16 位值。二值图像返回 1 位值。

对于 JPEG 图像，"[]" 允许你以字节数组的形式访问压缩的 JPEG 图像数据块。但由于 JPEG 图像是压缩字节流，对该数据数组的读写是不透明的。

图像还支持读缓冲区操作。你可以把图像传给各种各样的 MicroPython 函数，就好像图像是一个字节数组对象一样。特别是，如果你想传输一幅图像，只需将它传给 UART/SPI/I2C 的写函数即可自动传输。

基本方法¶

width() → int¶: 返回图像的宽度（以像素为单位）。

height() → int¶: 返回图像的高度（以像素为单位）。

format() → int¶: 对于灰度图像返回 image.GRAYSCALE，对于 RGB565 图像返回 image.RGB565，对于 bayer 模式图像返回 image.BAYER，对于 JPEG 图像返回 image.JPEG。

size() → int¶: 返回图像的大小（以字节为单位）。

bytearray() → bytearray¶: 返回一个指向图像数据的 bytearray 对象，用于字节级的读/写访问。

备注

当图像对象被传递给需要类 bytes 对象的 MicroPython 驱动程序时，会被自动转换为 bytes 对象。这是只读访问。调用 bytearray() 以获得读/写访问。

get_pixel(x: int, y: int, rgbtuple: bool | None = None) → int | Tuple[int, int, int]¶

对于灰度图像：返回位置 (x, y) 处的灰度像素值。对于 RGB565 图像：返回位置 (x, y) 处的 RGB888 像素元组 (r, g, b)。对于 bayer 模式图像：返回位置 (x, y) 处的像素值。

如果 x 或 y 超出图像范围，则返回 None。

x 和 y 既可以分别传入，也可以作为一个元组传入。

rgbtuple 若为 True，则此方法返回一个 RGB888 元组。否则，此方法返回底层像素的整数值。即对于 RGB565 图像，此方法返回 RGB565 值。对于 RGB565 图像默认为 True，其他情况下默认为 False。

不支持压缩图像。

备注

Image.get_pixel() 和 Image.set_pixel() 是仅有的允许你操作 bayer 模式图像的方法。Bayer 模式图像是字面意义上的图像，其中偶数行的像素为 R/G/R/G/等，奇数行的像素为 G/B/G/B/等。每个像素为 8 位。如果你在调用此方法时设置了 rgbtuple，则 Image.get_pixel() 会对该像素位置的源图像进行去马赛克处理，并为该像素位置返回一个有效的 RGB888 元组。

set_pixel(x: int, y: int, pixel: int | Tuple[int, int, int]) → Image¶

对于灰度图像：将位置 (x, y) 处的像素设置为灰度值 pixel。对于 RGB565 图像：将位置 (x, y) 处的像素设置为 RGB888 元组 (r, g, b) pixel。对于 bayer 模式图像：将位置 (x, y) 处的像素值设置为值 pixel。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

x 和 y 既可以分别传入，也可以作为一个元组传入。

pixel 既可以是 RGB888 元组 (r, g, b)，也可以是底层像素值（即对于 RGB565 图像为 RGB565 值，或对于灰度图像为 8 位值）。

不支持压缩图像。

备注

Image.get_pixel() 和 Image.set_pixel() 是仅有的允许你操作 bayer 模式图像的方法。Bayer 模式图像是字面意义上的图像，其中偶数行的像素为 R/G/R/G/等，奇数行的像素为 G/B/G/B/等。每个像素为 8 位。如果你以一个 RGB888 元组调用此方法，则会提取该 RGB888 元组的灰度值并设置到该像素位置。

转换方法¶

to_ndarray(dtype: str, buffer: bytes | bytearray | memoryview | None = None) → ndarray¶

返回一个从图像创建的 ndarray 对象。目前这仅适用于 GRAYSCALE 或 RGB565 图像。

dtype 可以是 b、B 或 f，分别用于创建有符号 8 位、无符号 8 位或 32 位浮点的 ndarray。GRAYSCALE 图像被直接转换为无符号 8 位 ndarray 对象。对于有符号 8 位 ndarray 对象，值 (0:255) 被映射到 (-127:128)。对于 float 32 位 ndarray 对象，值被映射到 (0.0:255.0)。RGB565 图像被转换为 3 通道的 ndarray 对象，并对每个通道根据 dtype 应用上述针对 GRAYSCALE 图像所描述的相同处理过程。注意，dtype 也接受 b、B 和 f 各自对应的整数值（例如 ord()）。

buffer 若不为 None，则是用作 ndarray 缓冲区的 bytearray 对象。如果为 None，则会在堆上分配一个新缓冲区来存储 ndarray 图像数据。你可以使用 buffer 参数将 ndarray 直接分配在预先分配好的缓冲区中，从而省去一次堆分配和一次复制操作。

返回的 ndarray 对于 GRAYSCALE 图像具有 (height, width) 的形状，对于 RGB565 图像具有 (height, width, 3) 的形状。

to_bitmap(x_scale: float = 1.0, y_scale: float = 1.0, roi: Tuple[int, int, int, int] | None = None, rgb_channel: int = -1, alpha: int = 255, color_palette: int | Image | None = None, alpha_palette: Image | None = None, hint: int = 0, transform: ndarray | None = None, copy: bool = False, copy_to_fb: bool = False) → Image¶

将图像转换为位图图像（每像素 1 位）。

x_scale 控制显示图像在 x 方向上的缩放比例（浮点数）。如果此值为负，图像将被水平翻转。注意，如果未指定 y_scale，它将与 x_scale 匹配以保持宽高比。

y_scale 控制显示图像在 y 方向上的缩放比例（浮点数）。如果此值为负，图像将被垂直翻转。注意，如果未指定 x_scale，它将与 x_scale 匹配以保持宽高比。

roi 是源图像中要绘制的感兴趣区域矩形元组 (x, y, w, h)。这允许你仅提取 ROI 中的像素进行缩放并绘制到目标图像上。

rgb_channel 是要从 RGB565 图像（若传入）中提取并渲染到目标图像上的 RGB 通道（0=R、G=1、B=2）。例如，如果你传入 rgb_channel=1，这将提取源 RGB565 图像的绿色通道并以灰度形式绘制到目标图像上。

alpha 控制将多少源图像混合到目标图像中。值为 255 时绘制不透明的源图像，而低于 255 的值则会在源图像与目标图像之间产生混合。0 则不会对目标图像做任何修改。

color_palette 若不为 None，可以是颜色调色板枚举值，或一个总计 256 像素的 RGB565 图像，用作针对源图像灰度值的颜色查找表。如果使用了 rgb_channel 提取，则此操作在其之后应用。

alpha_palette 若不为 None，可以是一个总计 256 像素的 GRAYSCALE 图像，用作 alpha 调色板，它在像素级别上调制被绘制源图像的 alpha 值，使你能够根据像素的灰度值精确控制其 alpha 值。alpha 查找表中值为 255 的像素是不透明的，小于 255 时越来越透明，直到 0。如果使用了 rgb_channel 提取，则此操作在其之后应用。

hint 是 Hint 标志中所列标志的逻辑或（不包括此处不支持的 image.BLACK_BACKGROUND）。

transform 是一个 3x3 的 ndarray，用于对图像执行透视变换。目前仅 OpenMV Cam N6 支持，因为它配有可以在硬件中完成此操作的 GPU。

copy 若为 True，则在堆上创建已转换图像的深拷贝，而不是就地转换原图像。

copy_to_fb 若为 True，则将图像直接加载到帧缓冲区中。copy_to_fb 优先于 copy。如果图像已在帧缓冲区中，则此参数没有特殊作用。

备注

位图图像类似于灰度图像，但只有两个像素值——0 和 1。此外，位图图像经过打包，每像素只存储 1 位，因此非常小巧。OpenMV 图像库允许位图图像用于所有可使用 sensor.GRAYSCALE 和 sensor.RGB565 图像的场合。但许多操作应用于位图图像时并没有任何意义，因为位图图像只有 2 个值。OpenMV 建议在操作中将位图图像用作 mask 值之类的用途，因为它们很容易放进 MicroPython 堆中。最后，当位图图像应用于 sensor.GRAYSCALE 或 sensor.RGB565 图像时，其像素值 0 和 1 被解释为黑色和白色。该库会自动处理转换。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

to_grayscale(x_scale: float = 1.0, y_scale: float = 1.0, roi: Tuple[int, int, int, int] | None = None, rgb_channel: int = -1, alpha: int = 255, color_palette: int | Image | None = None, alpha_palette: Image | None = None, hint: int = 0, transform: ndarray | None = None, copy: bool = False, copy_to_fb: bool = False) → Image¶

将图像转换为灰度图像（每像素 8 位）。

roi 是源图像中要绘制的感兴趣区域矩形元组 (x, y, w, h)。这允许你仅提取 ROI 中的像素进行缩放并绘制到目标图像上。

hint 是 Hint 标志中所列标志的逻辑或（不包括此处不支持的 image.BLACK_BACKGROUND）。

transform 是一个 3x3 的 ndarray，用于对图像执行透视变换。目前仅 OpenMV Cam N6 支持，因为它配有可以在硬件中完成此操作的 GPU。

copy 若为 True，则在堆上创建已转换图像的深拷贝，而不是就地转换原图像。

copy_to_fb 若为 True，则将图像直接加载到帧缓冲区中。copy_to_fb 优先于 copy。如果图像已在帧缓冲区中，则此参数没有特殊作用。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

to_rgb565(x_scale: float = 1.0, y_scale: float = 1.0, roi: Tuple[int, int, int, int] | None = None, rgb_channel: int = -1, alpha: int = 255, color_palette: int | Image | None = None, alpha_palette: Image | None = None, hint: int = 0, transform: ndarray | None = None, copy: bool = False, copy_to_fb: bool = False) → Image¶

将图像转换为 RGB565 图像（每像素 16 位）。

roi 是源图像中要绘制的感兴趣区域矩形元组 (x, y, w, h)。这允许你仅提取 ROI 中的像素进行缩放并绘制到目标图像上。

hint 是 Hint 标志中所列标志的逻辑或（不包括此处不支持的 image.BLACK_BACKGROUND）。

transform 是一个 3x3 的 ndarray，用于对图像执行透视变换。目前仅 OpenMV Cam N6 支持，因为它配有可以在硬件中完成此操作的 GPU。

copy 若为 True，则在堆上创建已转换图像的深拷贝，而不是就地转换原图像。

copy_to_fb 若为 True，则将图像直接加载到帧缓冲区中。copy_to_fb 优先于 copy。如果图像已在帧缓冲区中，则此参数没有特殊作用。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

to_rainbow(x_scale: float = 1.0, y_scale: float = 1.0, roi: Tuple[int, int, int, int] | None = None, rgb_channel: int = -1, alpha: int = 255, color_palette: int | Image = PALETTE_RAINBOW, alpha_palette: Image | None = None, hint: int = 0, transform: ndarray | None = None, copy: bool = False, copy_to_fb: bool = False) → Image¶

将图像转换为 RGB565 彩虹图像（每像素 16 位）。

roi 是源图像中要绘制的感兴趣区域矩形元组 (x, y, w, h)。这允许你仅提取 ROI 中的像素进行缩放并绘制到目标图像上。

hint 是 Hint 标志中所列标志的逻辑或（不包括此处不支持的 image.BLACK_BACKGROUND）。

transform 是一个 3x3 的 ndarray，用于对图像执行透视变换。目前仅 OpenMV Cam N6 支持，因为它配有可以在硬件中完成此操作的 GPU。

copy 若为 True，则在堆上创建已转换图像的深拷贝，而不是就地转换原图像。

copy_to_fb 若为 True，则将图像直接加载到帧缓冲区中。copy_to_fb 优先于 copy。如果图像已在帧缓冲区中，则此参数没有特殊作用。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

to_ironbow(x_scale: float = 1.0, y_scale: float = 1.0, roi: Tuple[int, int, int, int] | None = None, rgb_channel: int = -1, alpha: int = 255, color_palette: int | Image = PALETTE_IRONBOW, alpha_palette: Image | None = None, hint: int = 0, transform: ndarray | None = None, copy: bool = False, copy_to_fb: bool = False) → Image¶

将图像转换为 RGB565 铁红（ironbow）图像（每像素 16 位）。

roi 是源图像中要绘制的感兴趣区域矩形元组 (x, y, w, h)。这允许你仅提取 ROI 中的像素进行缩放并绘制到目标图像上。

hint 是 Hint 标志中所列标志的逻辑或（不包括此处不支持的 image.BLACK_BACKGROUND）。

transform 是一个 3x3 的 ndarray，用于对图像执行透视变换。目前仅 OpenMV Cam N6 支持，因为它配有可以在硬件中完成此操作的 GPU。

copy 若为 True，则在堆上创建已转换图像的深拷贝，而不是就地转换原图像。

copy_to_fb 若为 True，则将图像直接加载到帧缓冲区中。copy_to_fb 优先于 copy。如果图像已在帧缓冲区中，则此参数没有特殊作用。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

to_depth(x_scale: float = 1.0, y_scale: float = 1.0, roi: Tuple[int, int, int, int] | None = None, rgb_channel: int = -1, alpha: int = 255, color_palette: int | Image = PALETTE_IRONBOW, alpha_palette: Image | None = None, hint: int = 0, transform: ndarray | None = None, copy: bool = False, copy_to_fb: bool = False) → Image¶

将图像转换为 RGB565 深度图像（每像素 16 位）。

roi 是源图像中要绘制的感兴趣区域矩形元组 (x, y, w, h)。这允许你仅提取 ROI 中的像素进行缩放并绘制到目标图像上。

color_palette 若不为 None，可以是 image.PALETTE_DEPTH，或一个总计 256 像素的 RGB565 图像，用作针对源图像灰度值的颜色查找表。如果使用了 rgb_channel 提取，则此操作在其之后应用。

hint 是 Hint 标志中所列标志的逻辑或（不包括此处不支持的 image.BLACK_BACKGROUND）。

transform 是一个 3x3 的 ndarray，用于对图像执行透视变换。目前仅 OpenMV Cam N6 支持，因为它配有可以在硬件中完成此操作的 GPU。

copy 若为 True，则在堆上创建已转换图像的深拷贝，而不是就地转换原图像。

copy_to_fb 若为 True，则将图像直接加载到帧缓冲区中。copy_to_fb 优先于 copy。如果图像已在帧缓冲区中，则此参数没有特殊作用。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

to_evt_dark(x_scale: float = 1.0, y_scale: float = 1.0, roi: Tuple[int, int, int, int] | None = None, rgb_channel: int = -1, alpha: int = 255, color_palette: int | Image = PALETTE_IRONBOW, alpha_palette: Image | None = None, hint: int = 0, transform: ndarray | None = None, copy: bool = False, copy_to_fb: bool = False) → Image¶

将图像转换为 RGB565 暗事件图像（每像素 16 位）。

roi 是源图像中要绘制的感兴趣区域矩形元组 (x, y, w, h)。这允许你仅提取 ROI 中的像素进行缩放并绘制到目标图像上。

hint 是 Hint 标志中所列标志的逻辑或（不包括此处不支持的 image.BLACK_BACKGROUND）。

transform 是一个 3x3 的 ndarray，用于对图像执行透视变换。目前仅 OpenMV Cam N6 支持，因为它配有可以在硬件中完成此操作的 GPU。

copy 若为 True，则在堆上创建已转换图像的深拷贝，而不是就地转换原图像。

copy_to_fb 若为 True，则将图像直接加载到帧缓冲区中。copy_to_fb 优先于 copy。如果图像已在帧缓冲区中，则此参数没有特殊作用。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

to_evt_light(x_scale: float = 1.0, y_scale: float = 1.0, roi: Tuple[int, int, int, int] | None = None, rgb_channel: int = -1, alpha: int = 255, color_palette: int | Image = PALETTE_IRONBOW, alpha_palette: Image | None = None, hint: int = 0, transform: ndarray | None = None, copy: bool = False, copy_to_fb: bool = False) → Image¶

将图像转换为 RGB565 亮事件图像（每像素 16 位）。

roi 是源图像中要绘制的感兴趣区域矩形元组 (x, y, w, h)。这允许你仅提取 ROI 中的像素进行缩放并绘制到目标图像上。

hint 是 Hint 标志中所列标志的逻辑或（不包括此处不支持的 image.BLACK_BACKGROUND）。

transform 是一个 3x3 的 ndarray，用于对图像执行透视变换。目前仅 OpenMV Cam N6 支持，因为它配有可以在硬件中完成此操作的 GPU。

copy 若为 True，则在堆上创建已转换图像的深拷贝，而不是就地转换原图像。

copy_to_fb 若为 True，则将图像直接加载到帧缓冲区中。copy_to_fb 优先于 copy。如果图像已在帧缓冲区中，则此参数没有特殊作用。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

to_jpeg(x_scale: float = 1.0, y_scale: float = 1.0, roi: Tuple[int, int, int, int] | None = None, rgb_channel: int = -1, alpha: int = 255, color_palette: int | Image | None = None, alpha_palette: Image | None = None, hint: int = 0, transform: ndarray | None = None, copy: bool = False, copy_to_fb: bool = False, quality: int = 90, subsampling: int = 0) → Image¶

将图像转换为 JPEG 图像。

roi 是源图像中要绘制的感兴趣区域矩形元组 (x, y, w, h)。这允许你仅提取 ROI 中的像素进行缩放并绘制到目标图像上。

hint 是 Hint 标志中所列标志的逻辑或（不包括此处不支持的 image.BLACK_BACKGROUND）。

transform 是一个 3x3 的 ndarray，用于对图像执行透视变换。目前仅 OpenMV Cam N6 支持，因为它配有可以在硬件中完成此操作的 GPU。

copy 若为 True，则在堆上创建已转换图像的深拷贝，而不是就地转换原图像。

copy_to_fb 若为 True，则将图像直接加载到帧缓冲区中。copy_to_fb 优先于 copy。如果图像已在帧缓冲区中，则此参数没有特殊作用。

quality 控制 jpeg 图像的压缩质量。取值范围为 0 到 100。

subsampling 可以是：

image.JPEG_SUBSAMPLING_AUTO：根据质量为图像使用最佳的子采样。

image.JPEG_SUBSAMPLING_444：使用 4:4:4 子采样。

image.JPEG_SUBSAMPLING_422：使用 4:2:2 子采样。

image.JPEG_SUBSAMPLING_420：使用 4:2:0 子采样。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

to_png(x_scale: float = 1.0, y_scale: float = 1.0, roi: Tuple[int, int, int, int] | None = None, rgb_channel: int = -1, alpha: int = 255, color_palette: int | Image | None = None, alpha_palette: Image | None = None, hint: int = 0, transform: ndarray | None = None, copy: bool = False, copy_to_fb: bool = False) → Image¶

将图像转换为 PNG 图像。

roi 是源图像中要绘制的感兴趣区域矩形元组 (x, y, w, h)。这允许你仅提取 ROI 中的像素进行缩放并绘制到目标图像上。

hint 是 Hint 标志中所列标志的逻辑或（不包括此处不支持的 image.BLACK_BACKGROUND）。

transform 是一个 3x3 的 ndarray，用于对图像执行透视变换。目前仅 OpenMV Cam N6 支持，因为它配有可以在硬件中完成此操作的 GPU。

copy 若为 True，则在堆上创建已转换图像的深拷贝，而不是就地转换原图像。

copy_to_fb 若为 True，则将图像直接加载到帧缓冲区中。copy_to_fb 优先于 copy。如果图像已在帧缓冲区中，则此参数没有特殊作用。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

compress(x_scale: float = 1.0, y_scale: float = 1.0, roi: Tuple[int, int, int, int] | None = None, rgb_channel: int = -1, alpha: int = 255, color_palette: int | Image | None = None, alpha_palette: Image | None = None, hint: int = 0, transform: ndarray | None = None, copy: bool = False, copy_to_fb: bool = False, quality: int = 90, subsampling: int = 0) → Image¶

将图像转换为 JPEG 图像。

roi 是源图像中要绘制的感兴趣区域矩形元组 (x, y, w, h)。这允许你仅提取 ROI 中的像素进行缩放并绘制到目标图像上。

hint 是 Hint 标志中所列标志的逻辑或（不包括此处不支持的 image.BLACK_BACKGROUND）。

transform 是一个 3x3 的 ndarray，用于对图像执行透视变换。目前仅 OpenMV Cam N6 支持，因为它配有可以在硬件中完成此操作的 GPU。

copy 若为 True，则在堆上创建已转换图像的深拷贝，而不是就地转换原图像。

copy_to_fb 若为 True，则将图像直接加载到帧缓冲区中。copy_to_fb 优先于 copy。如果图像已在帧缓冲区中，则此参数没有特殊作用。

quality 控制 jpeg 图像的压缩质量。取值范围为 0 到 100。

subsampling 可以是：

image.JPEG_SUBSAMPLING_AUTO：根据质量为图像使用最佳的子采样。

image.JPEG_SUBSAMPLING_444：使用 4:4:4 子采样。

image.JPEG_SUBSAMPLING_422：使用 4:2:2 子采样。

image.JPEG_SUBSAMPLING_420：使用 4:2:0 子采样。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

备注

Image.compress 是 Image.to_jpeg 的别名。

copy(x_scale: float = 1.0, y_scale: float = 1.0, roi: Tuple[int, int, int, int] | None = None, rgb_channel: int = -1, alpha: int = 255, color_palette: int | Image | None = None, alpha_palette: Image | None = None, hint: int = 0, transform: ndarray | None = None, copy_to_fb: bool = False) → Image¶

创建图像对象的深拷贝。

roi 是源图像中要绘制的感兴趣区域矩形元组 (x, y, w, h)。这允许你仅提取 ROI 中的像素进行缩放并绘制到目标图像上。

hint 是 Hint 标志中所列标志的逻辑或（不包括此处不支持的 image.BLACK_BACKGROUND）。

transform 是一个 3x3 的 ndarray，用于对图像执行透视变换。目前仅 OpenMV Cam N6 支持，因为它配有可以在硬件中完成此操作的 GPU。

copy_to_fb 若为 True，则将图像直接加载到帧缓冲区中。如果图像已在帧缓冲区中，则此参数没有特殊作用。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

crop(x_scale: float = 1.0, y_scale: float = 1.0, roi: Tuple[int, int, int, int] | None = None, rgb_channel: int = -1, alpha: int = 255, color_palette: int | Image | None = None, alpha_palette: Image | None = None, hint: int = 0, transform: ndarray | None = None, copy: bool = False, copy_to_fb: bool = False) → Image¶

就地修改图像，且不改变底层图像类型。

roi 是源图像中要绘制的感兴趣区域矩形元组 (x, y, w, h)。这允许你仅提取 ROI 中的像素进行缩放并绘制到目标图像上。

hint 是 Hint 标志中所列标志的逻辑或（不包括此处不支持的 image.BLACK_BACKGROUND）。

transform 是一个 3x3 的 ndarray，用于对图像执行透视变换。目前仅 OpenMV Cam N6 支持，因为它配有可以在硬件中完成此操作的 GPU。

copy 若为 True，则在堆上创建已转换图像的深拷贝，而不是就地转换原图像。

copy_to_fb 若为 True，则将图像直接加载到帧缓冲区中。copy_to_fb 优先于 copy。如果图像已在帧缓冲区中，则此参数没有特殊作用。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

scale(x_scale: float = 1.0, y_scale: float = 1.0, roi: Tuple[int, int, int, int] | None = None, rgb_channel: int = -1, alpha: int = 255, color_palette: int | Image | None = None, alpha_palette: Image | None = None, hint: int = 0, transform: ndarray | None = None, copy: bool = False, copy_to_fb: bool = False) → Image¶

就地修改图像，且不改变底层图像类型。

roi 是源图像中要绘制的感兴趣区域矩形元组 (x, y, w, h)。这允许你仅提取 ROI 中的像素进行缩放并绘制到目标图像上。

hint 是 Hint 标志中所列标志的逻辑或（不包括此处不支持的 image.BLACK_BACKGROUND）。

transform 是一个 3x3 的 ndarray，用于对图像执行透视变换。目前仅 OpenMV Cam N6 支持，因为它配有可以在硬件中完成此操作的 GPU。

copy 若为 True，则在堆上创建已转换图像的深拷贝，而不是就地转换原图像。

copy_to_fb 若为 True，则将图像直接加载到帧缓冲区中。copy_to_fb 优先于 copy。如果图像已在帧缓冲区中，则此参数没有特殊作用。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

备注

Image.scale 是 Image.crop 的别名。

save(path: str, roi: Tuple[int, int, int, int] | None = None, quality: int = 50) → Image¶

将图像的副本保存到文件系统中的 path 处。

支持 bmp/pgm/ppm/jpg/jpeg 图像文件。注意，你无法将 jpeg 压缩图像保存为未压缩格式。

roi 是要从中保存的感兴趣区域矩形 (x, y, w, h)。如果未指定，则等于整个图像矩形，即复制整幅图像。此参数不适用于 JPEG 图像。

quality 是当图像尚未压缩时，将图像保存为 jpeg 格式所使用的 jpeg 压缩质量 (0-100)（整数）。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

flush() → None¶: 用摄像头帧缓冲区中的图像更新 IDE 中的帧缓冲区。

绘制方法¶

clear(mask: Image | None = None) → Image¶

将图像中的所有像素置零（非常快）。

mask 是用作该操作像素级掩码的另一幅图像。掩码应是一幅只有黑色或白色像素的图像，且应与被操作的图像大小相同。只有掩码中被置位的像素才会被修改。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

不支持压缩图像。

draw_line(x0: int, y0: int, x1: int, y1: int, color: int | Tuple[int, int, int] | None = None, thickness: int = 1) → Image¶

在图像上从 (x0, y0) 到 (x1, y1) 绘制一条线。你既可以分别传入 x0、y0、x1、y1，也可以作为一个元组 (x0, y0, x1, y1) 传入。

color 对于灰度或 RGB565 图像是一个 RGB888 元组。默认为白色。不过，你也可以为灰度图像传入底层像素值 (0-255)，或为 RGB565 图像传入 RGB565 值。

thickness 控制线条的粗细（以像素为单位）。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

不支持压缩图像或 bayer 图像。

draw_rectangle(x: int, y: int, w: int, h: int, color: int | Tuple[int, int, int] | None = None, thickness: int = 1, fill: bool = False) → Image¶

在图像上绘制一个矩形。你既可以分别传入 x、y、w、h，也可以作为一个元组 (x, y, w, h) 传入。

color 对于灰度或 RGB565 图像是一个 RGB888 元组。默认为白色。不过，你也可以为灰度图像传入底层像素值 (0-255)，或为 RGB565 图像传入 RGB565 值。

thickness 控制线条的粗细（以像素为单位）。

将 fill 设置为 True 以填充矩形。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

不支持压缩图像或 bayer 图像。

draw_circle(x: int, y: int, radius: int, color: int | Tuple[int, int, int] | None = None, thickness: int = 1, fill: bool = False) → Image¶

在图像上绘制一个圆。你既可以分别传入 x、y、radius，也可以作为一个元组 (x, y, radius) 传入。

color 对于灰度或 RGB565 图像是一个 RGB888 元组。默认为白色。不过，你也可以为灰度图像传入底层像素值 (0-255)，或为 RGB565 图像传入 RGB565 值。

thickness 控制边缘的粗细（以像素为单位）。

将 fill 设置为 True 以填充圆。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

不支持压缩图像或 bayer 图像。

draw_ellipse(cx: int, cy: int, rx: int, ry: int, rotation: int, color: int | Tuple[int, int, int] | None = None, thickness: int = 1, fill: bool = False) → Image¶

在图像上绘制一个椭圆。你既可以分别传入 cx、cy、rx、ry 和旋转角度（以度为单位），也可以作为一个元组 (cx, yc, rx, ry, rotation) 传入。

color 对于灰度或 RGB565 图像是一个 RGB888 元组。默认为白色。不过，你也可以为灰度图像传入底层像素值 (0-255)，或为 RGB565 图像传入 RGB565 值。

thickness 控制边缘的粗细（以像素为单位）。

将 fill 设置为 True 以填充椭圆。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

不支持压缩图像或 bayer 图像。

draw_string(x: int, y: int, text: str, color: int | Tuple[int, int, int] | None = None, scale: float = 1, x_spacing: int = 0, y_spacing: int = 0, mono_space: bool = True, char_rotation: int = 0, char_hmirror: bool = False, char_vflip: bool = False, string_rotation: int = 0, string_hmirror: bool = False, string_vflip: bool = False) → Image¶

从图像中位置 (x, y) 处开始绘制 8x10 的文本。你既可以分别传入 x、y，也可以作为一个元组 (x, y) 传入。

text 是要写到图像上的字符串。\n、\r 和 \r\n 行结束符会将光标移到下一行。

color 对于灰度或 RGB565 图像是一个 RGB888 元组。默认为白色。不过，你也可以为灰度图像传入底层像素值 (0-255)，或为 RGB565 图像传入 RGB565 值。

可增大 scale 来增大/减小图像上文本的大小。你可以传入大于 0 的整数或浮点数值。

x_spacing 允许你在字符之间增加（若为正）或减少（若为负）x 像素。

y_spacing 允许你在字符之间增加（若为正）或减少（若为负）y 像素（用于多行文本）。

mono_space 默认为 True，强制文本采用固定间距。对于较大的文本缩放比例，这看起来很糟糕。设置为 False 可获得非固定宽度的字符间距，看起来要好得多。

char_rotation 可以是 0、90、180、270，用于将字符串中的每个字符旋转此角度。

char_hmirror 若为 True，则水平镜像字符串中的所有字符。

char_vflip 若为 True，则垂直翻转字符串中的所有字符。

string_rotation 可以是 0、90、180、270，用于将字符串旋转此角度。

string_hmirror 若为 True，则水平镜像字符串。

string_vflip 若为 True，则垂直翻转字符串。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

不支持压缩图像或 bayer 图像。

draw_cross(x: int, y: int, color: int | Tuple[int, int, int] | None = None, size: int = 5, thickness: int = 1) → Image¶

在位置 x, y 处绘制一个十字。你既可以分别传入 x、y，也可以作为一个元组 (x, y) 传入。

color 对于灰度或 RGB565 图像是一个 RGB888 元组。默认为白色。不过，你也可以为灰度图像传入底层像素值 (0-255)，或为 RGB565 图像传入 RGB565 值。

size 控制十字线条延伸的长度。

thickness 控制边缘的粗细（以像素为单位）。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

不支持压缩图像或 bayer 图像。

draw_arrow(x0: int, y0: int, x1: int, y1: int, color: int | Tuple[int, int, int] | None = None, thickness: int = 1) → Image¶

在图像上从 (x0, y0) 到 (x1, y1) 绘制一个箭头。你既可以分别传入 x0、y0、x1、y1，也可以作为一个元组 (x0, y0, x1, y1) 传入。

color 对于灰度或 RGB565 图像是一个 RGB888 元组。默认为白色。不过，你也可以为灰度图像传入底层像素值 (0-255)，或为 RGB565 图像传入 RGB565 值。

thickness 控制线条的粗细（以像素为单位）。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

不支持压缩图像或 bayer 图像。

draw_detection(detection: Tuple[int, int, int, int, int, int], color1: int | Tuple[int, int, int] | None = None, color2: int | Tuple[int, int, int] | None = None, size: int = 5, thickness: int = 1, fill: bool = False, label: str | None = None, label_offset: Tuple[int, int] | None = None) → Image¶

在图像上绘制一个检测结果。detection 是一个 6 元组 (rx, ry, rw, rh, cx, cy)，描述一个边界矩形和一个质心（通常由神经网络或颜色跟踪代码返回）。

color1 是矩形颜色，color2 是质心十字颜色。size 是质心十字的大小，thickness 控制轮廓宽度，fill 填充矩形。

若提供 label，则会绘制在矩形附近，并按 label_offset (x, y) 偏移。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

不支持压缩图像或 bayer 图像。

draw_edges(corners: List[Tuple[int, int]], color: int | Tuple[int, int, int] | None = None, size: int = 0, thickness: int = 1, fill: bool = False) → Image¶

在由 blob.corners 等方法返回的角点列表之间绘制连线边缘。Corners 是一个四元组，每个元素是二元的 x/y 元组。例如 [(x1,y1),(x2,y2),(x3,y3),(x4,y4)]。

color 对于灰度或 RGB565 图像是一个 RGB888 元组。默认为白色。不过，你也可以为灰度图像传入底层像素值 (0-255)，或为 RGB565 图像传入 RGB565 值。

若 size 大于 0，则将角点绘制为半径为 size 的圆。

thickness 控制线条的粗细（以像素为单位）。

若绘制了角点圆，将 fill 设置为 True 以填充它们。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

不支持压缩图像或 bayer 图像。

draw_image(image: Image, x: int = 0, y: int = 0, x_scale: float = 1.0, y_scale: float = 1.0, roi: Tuple[int, int, int, int] | None = None, rgb_channel: int = -1, alpha: int = 255, color_palette: int | Image | None = None, alpha_palette: Image | None = None, hint: int = 0, transform: ndarray | None = None, mask: Image | None = None) → Image¶

绘制一幅 image，其左上角从位置 x, y 处开始。你既可以分别传入 x、y，也可以作为一个元组 (x, y) 传入。此方法会自动处理将传入的图像渲染为目标图像的正确像素格式，同时无缝处理裁剪。

你也可以为此方法传入一个路径而非图像对象，从而一步自动从磁盘加载图像并使用它。例如 draw_image("test.jpg")。

roi 是源图像中要绘制的感兴趣区域矩形元组 (x, y, w, h)。这允许你仅提取 ROI 中的像素进行缩放并绘制到目标图像上。

hint 是 Hint 标志中所列标志的逻辑或（包括此处支持的 image.BLACK_BACKGROUND）。

transform 是一个 3x3 的 ndarray，用于对图像执行透视变换。目前仅 OpenMV Cam N6 支持，因为它配有可以在硬件中完成此操作的 GPU。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

draw_keypoints(keypoints: kp_desc | List[Tuple[int, int, int]], color: int | Tuple[int, int, int] | None = None, size: int = 10, thickness: int = 1, fill: bool = False) → Image¶

在图像上绘制 keypoints 对象的关键点。你也可以传入一个三值元组列表，元组包含 (x, y, rotation_angle_in_degrees)，以复用此方法来绘制关键点图标，即一个带有指向特定方向的线的圆。

color 对于灰度或 RGB565 图像是一个 RGB888 元组。默认为白色。不过，你也可以为灰度图像传入底层像素值 (0-255)，或为 RGB565 图像传入 RGB565 值。

size 控制关键点的大小。

thickness 控制线条的粗细（以像素为单位）。

将 fill 设置为 True 以填充关键点。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

不支持压缩图像或 bayer 图像。

flood_fill(x: int, y: int, seed_threshold: float = 0.05, floating_threshold: float = 0.05, color: int | Tuple[int, int, int] | None = None, invert: bool = False, clear_background: bool = False, mask: Image | None = None) → Image¶

从位置 x, y 处开始对图像的一个区域进行漫水填充。你既可以分别传入 x、y，也可以作为一个元组 (x, y) 传入。

seed_threshold 控制填充区域中任意像素与最初起始像素之间可允许的差异程度。

floating_threshold 控制填充区域中任意像素与任意相邻像素之间可允许的差异程度。

color 对于灰度或 RGB565 图像是一个 RGB888 元组。默认为白色。不过，你也可以为灰度图像传入底层像素值 (0-255)，或为 RGB565 图像传入 RGB565 值。

将 invert 传为 True，可对漫水填充连通区域之外的所有内容重新着色。

将 clear_background 传为 True，可将漫水填充未重新着色的其余像素置零。

mask 是用作该操作像素级掩码的另一幅图像。掩码应是一幅只有黑色或白色像素的图像，且应与被操作的图像大小相同。漫水填充时只有掩码中被置位的像素才会被纳入评估。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

不支持压缩图像或 bayer 图像。

此方法在 OpenMV Cam M4 上不可用。

draw_event_histogram(array: ndarray, clear: bool = True, brightness: int = 128, contrast: int = 16) → Image¶

将一个事件 ndarray（如 csi.IOCTL_GENX320_READ_EVENTS 所填充的）栅格化到一个 Image 上以进行可视化。图像缓冲区必须是一幅 320x320 的 GRAYSCALE 图像。

对于每个 csi.PIX_ON_EVENT 行，该事件的像素会被加上 +contrast；对于每个 csi.PIX_OFF_EVENT 行，该像素会被加上 -contrast。触发事件会被忽略。像素值会被钳制到 0-255。

clear 若为 True，则在绘制之前将图像缓冲区重置为 brightness——每一帧都成为一次全新的仅事件渲染。设置为 False 可在多次调用之间累积事件（对于长曝光运动轨迹很有用）。

brightness 控制当 clear 为 True 时缓冲区被重置到的中灰基线。默认值 128 将 ON 事件置于明亮端、OFF 事件置于黑暗端，且两端余量相等。

contrast 控制每个事件使其像素偏移的幅度——较高的值会使事件更突出，但代价是当许多事件落在同一像素上时会很快饱和。

掩码方法¶

mask_rectangle(x: int, y: int, w: int, h: int) → Image¶

将图像的一个矩形部分置零。如果未提供任何参数，则此方法将图像的中心置零。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

不支持压缩图像或 bayer 图像。

mask_circle(x: int, y: int, radius: int) → Image¶

将图像的一个圆形部分置零。如果未提供任何参数，则此方法将图像的中心置零。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

不支持压缩图像或 bayer 图像。

mask_ellipse(x: int, y: int, radius_x: int, radius_y: int, rotation_angle_in_degrees: int) → Image¶

将图像的一个椭圆形部分置零。如果未提供任何参数，则此方法将图像的中心置零。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

不支持压缩图像或 bayer 图像。

二值方法¶

binary(thresholds: List[Tuple[int, int]], invert: bool = False, zero: bool = False, mask: Image | None = None, to_bitmap: bool = False, copy: bool = False) → Image¶

根据每个像素是否落在 thresholds 中某个阈值元组之内，将图像中的所有像素设置为黑色或白色。

thresholds 对于灰度图像是 (lo, hi) 元组的列表，对于 RGB565 图像是 (l_lo, l_hi, a_lo, a_hi, b_lo, b_hi) 元组的列表。min/max 值颠倒时会被自动修正；缺失的分量默认取最大范围。

invert 反转阈值匹配。

zero 若为 True，则将阈值内的像素置零，并保留其他像素不变。

mask 是一幅用作像素级掩码的二值图像；只有掩码中被置位的像素才会被修改。

to_bitmap 若为 True，则将图像数据转换为每像素 1 位的位图。对于非常小的图像，这可能需要 copy=True。

copy 若为 True，则在堆上返回一幅新图像，而不是修改源图像。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

不支持压缩图像或 bayer 图像。

invert() → Image¶

反转图像中的所有像素值（对于 8 位通道，每个像素变为 255 - pixel）。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

不支持压缩图像或 bayer/yuv 图像。

b_and(image: Image, mask: Image | None = None) → Image¶

将此图像与另一幅图像进行逻辑与（AND）运算。

image 可以是一个图像对象、一个指向未压缩图像文件（bmp/pgm/ppm）的路径，或一个标量值（RGB888 元组或底层像素值）。

mask 是一幅用作像素级掩码的二值图像；只有掩码中被置位的像素才会被修改。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

不支持压缩图像或 bayer 图像。

b_nand(image: Image, mask: Image | None = None) → Image¶

将此图像与另一幅图像进行逻辑与非（NAND）运算。

image 可以是一个图像对象、一个指向未压缩图像文件（bmp/pgm/ppm）的路径，或一个标量值（RGB888 元组或底层像素值）。

mask 是一幅用作像素级掩码的二值图像；只有掩码中被置位的像素才会被修改。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

不支持压缩图像或 bayer 图像。

b_or(image: Image, mask: Image | None = None) → Image¶

将此图像与另一幅图像进行逻辑或（OR）运算。

image 可以是一个图像对象、一个指向未压缩图像文件（bmp/pgm/ppm）的路径，或一个标量值（RGB888 元组或底层像素值）。

mask 是一幅用作像素级掩码的二值图像；只有掩码中被置位的像素才会被修改。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

不支持压缩图像或 bayer 图像。

b_nor(image: Image, mask: Image | None = None) → Image¶

将此图像与另一幅图像进行逻辑或非（NOR）运算。

image 可以是一个图像对象、一个指向未压缩图像文件（bmp/pgm/ppm）的路径，或一个标量值（RGB888 元组或底层像素值）。

mask 是一幅用作像素级掩码的二值图像；只有掩码中被置位的像素才会被修改。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

不支持压缩图像或 bayer 图像。

b_xor(image: Image, mask: Image | None = None) → Image¶

将此图像与另一幅图像进行逻辑异或（XOR）运算。

image 可以是一个图像对象、一个指向未压缩图像文件（bmp/pgm/ppm）的路径，或一个标量值（RGB888 元组或底层像素值）。

mask 是一幅用作像素级掩码的二值图像；只有掩码中被置位的像素才会被修改。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

不支持压缩图像或 bayer 图像。

b_xnor(image: Image, mask: Image | None = None) → Image¶

将此图像与另一幅图像进行逻辑同或（XNOR）运算。

image 可以是一个图像对象、一个指向未压缩图像文件（bmp/pgm/ppm）的路径，或一个标量值（RGB888 元组或底层像素值）。

mask 是一幅用作像素级掩码的二值图像；只有掩码中被置位的像素才会被修改。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

不支持压缩图像或 bayer 图像。

ISP 方法¶

awb(max: bool = False) → Image¶

使用灰度世界（gray-world）算法对图像执行自动白平衡。可在原始 Bayer 或 RGB565 图像上操作。对二值/灰度图像无效。

max 若为 True，则改用白块（white-patch）算法。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

不支持压缩图像或 yuv 图像。

ccm(matrix: List[List[float]]) → Image¶

将传入的浮点颜色校正矩阵与图像相乘。矩阵可以是 3x3 或 3x4（带偏移列），采用嵌套列表或扁平列表形式:

[[rr, rg, rb], [gr, gg, gb], [br, bg, bb]]
[[rr, rg, rb, ro], [gr, gg, gb, go], [br, bg, bb, bo]]
[rr, rg, rb, ro, gr, gg, gb, go, br, bg, bb, bo]

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

不支持压缩图像或 bayer/yuv 图像。

gamma(gamma: float = 1.0, contrast: float = 1.0, brightness: float = 0.0) → Image¶

调整图像的伽马（gamma）、对比度和亮度。

gamma 在归一化后应用 pow(pixel, 1/gamma)。大于 1.0 的值会变亮；小于 1.0 的值会变暗。

contrast 在归一化后应用 pixel * contrast。

brightness 在归一化后应用 pixel + brightness。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

不支持压缩图像或 bayer/yuv 图像。

gamma_corr(gamma: float = 1.0, contrast: float = 1.0, brightness: float = 0.0) → Image¶: Image.gamma 的别名。

数学方法¶

negate() → Image¶: Image.invert 的别名。

replace(image: Image | None = None, **kwargs) → Image¶: Image.draw_image() 的别名。使用标准的 draw_image 关键字参数，用 image 替换此图像（或者如果省略 image 则就地变换此图像）。transform 参数是一个描述透视变换的 3x3 ndarray（仅在启用了 ULAB 的 OpenMV 摄像头上支持）。

assign(image: Image | None = None, **kwargs) → Image¶: Image.replace() 的别名。

set(image: Image | None = None, **kwargs) → Image¶: Image.replace() 的别名。

add(image: Image, mask: Image | None = None) → Image¶

将一幅图像逐像素地加到此图像上。

image 可以是一个图像对象、一个指向未压缩图像文件（bmp/pgm/ppm）的路径，或一个标量值（RGB888 元组或底层像素值）。

mask 是一幅用作像素级掩码的二值图像；只有掩码中被置位的像素才会被修改。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

不支持压缩图像或 bayer 图像。

sub(image: Image, mask: Image | None = None) → Image¶

从此图像中逐像素地减去 image（self - image）。

image 既可以是一个图像对象、一个指向未压缩图像文件（bmp/pgm/ppm）的路径，也可以是一个标量值（RGB888 元组或底层像素值）。

mask 是一幅用作像素级掩码的二值图像；只有掩码中被置位的像素才会被修改。

此方法还接受 Image.draw_image() 的全部关键字参数（x、y、x_scale、y_scale、roi、rgb_channel、alpha、color_palette、alpha_palette、hint、transform）。

不支持压缩图像或 bayer 图像。

rsub(image: Image, mask: Image | None = None) → Image¶: 反向减法：用 image - self 逐像素地替换此图像。其余与 Image.sub() 相同。

min(image: Image, mask: Image | None = None) → Image¶

返回两幅图像逐像素的最小值图像。

image 可以是一个图像对象、一个指向未压缩图像文件（bmp/pgm/ppm）的路径，或一个标量值（RGB888 元组或底层像素值）。

mask 是一幅用作像素级掩码的二值图像；只有掩码中被置位的像素才会被修改。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

不支持压缩图像或 bayer 图像。

max(image: Image, mask: Image | None = None) → Image¶

返回两幅图像逐像素的最大值图像。

image 可以是一个图像对象、一个指向未压缩图像文件（bmp/pgm/ppm）的路径，或一个标量值（RGB888 元组或底层像素值）。

mask 是一幅用作像素级掩码的二值图像；只有掩码中被置位的像素才会被修改。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

不支持压缩图像或 bayer 图像。

difference(image: Image, mask: Image | None = None) → Image¶

返回两幅图像之间的绝对差图像（例如 ||a-b||）。

image 可以是一个图像对象、一个指向未压缩图像文件（bmp/pgm/ppm）的路径，或一个标量值（RGB888 元组或底层像素值）。

mask 是一幅用作像素级掩码的二值图像；只有掩码中被置位的像素才会被修改。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

不支持压缩图像或 bayer 图像。

blend(image: Image, x: int = 0, y: int = 0, alpha: int = 128, mask: Image | None = None, **kwargs) → Image¶: Image.draw_image() 的别名。将 image 与此图像进行 alpha 混合。alpha 是 0-256 的整数；越接近 256 越偏向源图像。接受所有 Image.draw_image() 关键字参数。

histeq(adaptive: bool = False, clip_limit: float = -1, mask: Image | None = None) → Image¶

对图像运行直方图均衡化以归一化对比度和亮度。

adaptive 若为 True，则运行自适应直方图均衡化（更慢但通常效果更好）。

clip_limit 在自适应变体中限制对比度（像 10 这样的较小值能产生良好的 CLAHE 结果）。

mask 是一幅用作像素级掩码的二值图像；只有掩码中被置位的像素才会被修改。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

不支持压缩图像或 bayer 图像。

滤波方法¶

erode(size: int, threshold: int | None = None, mask: Image | None = None) → Image¶

从分割区域的边缘移除像素。在图像上卷积一个 ((size*2)+1)x((size*2)+1) 的核，如果有超过 threshold 个相邻像素被清除，则清除中心像素（当 threshold 为 None 时表现为标准腐蚀）。

mask 是一幅用作像素级掩码的二值图像；只有掩码中被置位的像素才会被修改。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

不支持压缩图像或 bayer/yuv 图像。

dilate(size: int, threshold: int | None = None, mask: Image | None = None) → Image¶

向分割区域的边缘添加像素。在图像上卷积一个 ((size*2)+1)x((size*2)+1) 的核，如果有超过 threshold 个相邻像素被置位，则置位中心像素（当 threshold 为 None 时表现为标准膨胀）。

mask 是一幅用作像素级掩码的二值图像；只有掩码中被置位的像素才会被修改。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

不支持压缩图像或 bayer/yuv 图像。

open(size: int, threshold: int | None = None, mask: Image | None = None) → Image¶

先执行腐蚀再执行膨胀。参见 Image.erode() 和 Image.dilate()。

mask 是一幅用作像素级掩码的二值图像；只有掩码中被置位的像素才会被修改。

不支持压缩图像或 bayer/yuv 图像。

close(size: int, threshold: int | None = None, mask: Image | None = None) → Image¶

先执行膨胀再执行腐蚀。参见 Image.dilate() 和 Image.erode()。

mask 是一幅用作像素级掩码的二值图像；只有掩码中被置位的像素才会被修改。

不支持压缩图像或 bayer/yuv 图像。

top_hat(size: int, threshold: int | None = None, mask: Image | None = None) → Image¶

返回图像与经 Image.open() 处理后的图像之间的图像差。

mask 是一幅用作像素级掩码的二值图像；只有掩码中被置位的像素才会被修改。

不支持压缩图像或 bayer/yuv 图像。

black_hat(size: int, threshold: int | None = None, mask: Image | None = None) → Image¶

返回图像与经 Image.close() 处理后的图像之间的图像差。

mask 是一幅用作像素级掩码的二值图像；只有掩码中被置位的像素才会被修改。

不支持压缩图像或 bayer/yuv 图像。

mean(size: int, threshold: bool | None = False, offset: int | None = 0, invert: bool | None = False, mask: Image | None = None) → Image¶

使用盒式滤波器（box filter）的标准均值模糊滤波器。

size 是核大小。使用 1（3x3 核）、2（5x5 核）等。

threshold 若为 True，则自适应地将滤波输出阈值化为二值图像。offset 移动二值化阈值（负值使更多像素变白，正值使更少像素变白）。invert 反转二值输出。

mask 是一幅用作像素级掩码的二值图像；只有掩码中被置位的像素才会被修改。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

不支持压缩图像或 bayer/yuv 图像。

对图像运行百分位滤波器（默认为中值）。

size 是核大小。使用 1（3x3 核）、2（5x5 核）等。

percentile 是从每个核中选取的百分位（0 = 最小值，0.5 = 中值，1.0 = 最大值）。默认为 0.5。

mask 是一幅用作像素级掩码的二值图像；只有掩码中被置位的像素才会被修改。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

不支持压缩图像或 bayer/yuv 图像。

mode(size: int, threshold: bool | None = False, offset: int | None = 0, invert: bool | None = False, mask: Image | None = None) → Image¶

用每个像素邻域的众数替换该像素。由于这是非线性操作，可能在 RGB 图像边缘产生伪影。

size 是核大小。使用 1（3x3 核）、2（5x5 核）等。

mask 是一幅用作像素级掩码的二值图像；只有掩码中被置位的像素才会被修改。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

不支持压缩图像或 bayer/yuv 图像。

对图像运行中点滤波器。此滤波器找出图像中每个像素邻域的中点 ((max-min)/2)。

size 是核大小。使用 1（3x3 核）、2（5x5 核）等。

bias 控制 min/max 的混合。0 表示仅 min 滤波，1.0 表示仅 max 滤波。通过使用 bias 你可以对图像进行 min/max 滤波。

mask 是一幅用作像素级掩码的二值图像；只有掩码中被置位的像素才会被修改。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

不支持压缩图像或 bayer/yuv 图像。

用任意滤波核对图像进行卷积。

size 控制核大小，核必须为 ((size*2)+1)x((size*2)+1) 个元素。

kernel 是要用于卷积的核，可以是一个包含 ((size*2)+1)*((size*2)+1) 个元素的扁平一维列表/元组，或一个包含 ((size*2)+1) 行、每行 ((size*2)+1) 个元素的二维列表/元组。

mul 是乘性对比度缩放（默认 1.0）。

add 是加性亮度偏移（默认 0.0）。

mask 是一幅用作像素级掩码的二值图像；只有掩码中被置位的像素才会被修改。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

不支持压缩图像或 bayer/yuv 图像。

用平滑的高斯核对图像进行卷积。

size 是核大小。使用 1（3x3 核）、2（5x5 核）等。

unsharp 若为 True，则执行非锐化掩蔽操作（锐化边缘）而非普通高斯模糊。

mul 是乘性对比度缩放（默认 1.0）。

add 是加性亮度偏移（默认 0.0）。

mask 是一幅用作像素级掩码的二值图像；只有掩码中被置位的像素才会被修改。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

不支持压缩图像或 bayer/yuv 图像。

laplacian(size: int, sharpen: bool | None = False, mul: float | None = 1.0, add: float | None = 0.0, threshold: bool | None = False, offset: int | None = 0, invert: bool | None = False, mask: Image | None = None) → Image¶: 用边缘检测拉普拉斯核对图像进行卷积。

size 是核大小。使用 1（3x3 核）、2（5x5 核）等。

sharpen 若为 True，则锐化图像，而非输出原始的未阈值化边缘响应。

mul 是乘性对比度缩放（默认 1.0）。

add 是加性亮度偏移（默认 0.0）。

threshold 若为 True，则自适应地将滤波输出阈值化为二值图像。offset 移动二值化阈值（负值使更多像素变白，正值使更少像素变白）。invert 反转二值输出。

mask 是一幅用作像素级掩码的二值图像；只有掩码中被置位的像素才会被修改。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

不支持压缩图像或 bayer/yuv 图像。

用双边滤波器（保边平滑）对图像进行卷积。

size 是核大小。使用 1（3x3 核）、2（5x5 核）等。

color_sigma 控制颜色匹配容差；值越大产生的颜色模糊越多。

space_sigma 控制空间模糊；值越大产生的像素模糊越多。

mask 是一幅用作像素级掩码的二值图像；只有掩码中被置位的像素才会被修改。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

不支持压缩图像或 bayer/yuv 图像。

几何方法¶

linpolar(reverse: bool = False, *, x: int | None = None, y: int | None = None) → Image¶

将图像从笛卡尔坐标重新投影到线性极坐标。

设置 reverse=True 以沿相反方向重新投影。

x 和 y 指定变换中心在图像中的坐标（以像素为单位）。如果 x 为 None（默认值），则将其设置为图像宽度的一半；同样，y 默认为图像高度的一半。

线性极坐标重新投影将图像的旋转转化为 x 方向的平移。

不支持压缩图像或 bayer 图像。

此方法在 OpenMV Cam M4 上不可用。

logpolar(reverse: bool = False, *, x: int | None = None, y: int | None = None) → Image¶

将图像从笛卡尔坐标重新投影到对数极坐标。

设置 reverse=True 以沿相反方向重新投影。

对数极坐标重新投影将图像的旋转转化为 x 方向的平移，将缩放/变焦转化为 y 方向的平移。

不支持压缩图像或 bayer 图像。

此方法在 OpenMV Cam M4 上不可用。

lens_corr(strength: float = 1.8, zoom: float = 1.0, x_corr: float = 0.0, y_corr: float = 0.0) → Image¶

执行镜头校正以消除由镜头畸变引起的鱼眼效果。

strength 是一个浮点数，定义对图像消除鱼眼效果的程度。默认先尝试 1.8，然后从该值起增大或减小，直到图像看起来令人满意。

zoom 是对图像进行放大的倍数。默认 1.0。

x_corr 相对于中心的浮点像素偏移。可以为负或为正。

y_corr 相对于中心的浮点像素偏移。可以为负或为正。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

不支持压缩图像或 bayer 图像。

rotation_corr(x_rotation: float = 0.0, y_rotation: float = 0.0, z_rotation: float = 0.0, x_translation: float = 0.0, y_translation: float = 0.0, zoom: float = 1.0, fov: float = 60.0, corners: List[Tuple[int, int]] | None = None) → Image¶

通过对帧缓冲区进行 3D 旋转来校正图像中的透视问题。

x_rotation 是图像在帧缓冲区中围绕 x 轴旋转的度数（即这会使图像上下翻转）。

y_rotation 是图像在帧缓冲区中围绕 y 轴旋转的度数（即这会使图像左右翻转）。

z_rotation 是图像在帧缓冲区中围绕 z 轴旋转的度数（即这会使图像原地旋转）。

x_translation 是旋转之后将图像向左或向右移动的单位数。由于此平移是在 3D 空间中应用的，因此单位不是像素……

y_translation 是旋转之后将图像向上或向下移动的单位数。由于此平移是在 3D 空间中应用的，因此单位不是像素……

zoom 是对图像进行放大的倍数。默认 1.0。

fov 是用于内部 2D->3D 投影的视场角。当 fov 趋近 0 时，图像被置于无穷远处；当它趋近 180 时，图像被置于视口之内。

corners 是四个 (x, y) 元组的列表，用于构建一个 4 点单应性，在应用 3D 旋转之前将这些角点映射到 (0, 0)、(image_width-1, 0)、(image_width-1, image_height-1) 和 (0, image_height-1)。对于鸟瞰视角变换很有用。

返回图像对象，以便你可以使用 . 表示法调用另一个方法。

不支持压缩图像或 bayer 图像。

此方法在 OpenMV Cam M4 上不可用。

Get 方法¶

get_similarity(image: Image, x: int = 0, y: int = 0, x_scale: float = 1.0, y_scale: float = 1.0, roi: Tuple[int, int, int, int] | None = None, rgb_channel: int = -1, alpha: int = 255, color_palette: int | Image | None = None, alpha_palette: Image | None = None, hint: int = 0, transform: ndarray | None = None, dssim: bool = False) → Similarity¶

使用结构相似性指数（SSIM）计算两幅图像之间的相似度。SSIM 的取值范围从 -1（相反）到 1（相同）。返回一个 image.similarity 对象。

image 是要比较的图像（一个图像对象或一个路径字符串，例如 "test.jpg"）。

x、y、x_scale、y_scale、roi、rgb_channel、alpha、color_palette、alpha_palette、hint 和 transform 接受与 Image.draw_image() 相同的值。

dssim 若为 True，则改为返回结构不相似性指数（DSSIM），其中 0 表示相同，1 表示完全不同。

get_histogram(thresholds: List[Tuple[int, int]] | None = None, invert: bool = False, roi: Tuple[int, int, int, int] | None = None, bins: int = -1, l_bins: int = -1, a_bins: int = -1, b_bins: int = -1, difference: Image | None = None) → histogram¶

对一个 roi 在所有颜色通道上计算归一化直方图，并返回一个 image.histogram 对象。也可通过 Image.get_hist() 或 Image.histogram() 调用。

thresholds 对于灰度图像是 (lo, hi) 元组的列表，对于 RGB565 图像是 (l_lo, l_hi, a_lo, a_hi, b_lo, b_hi) 元组的列表。如果传入，则仅在阈值内的像素上计算直方图。

invert 反转阈值匹配。

roi 是感兴趣区域矩形元组 (x, y, w, h)。默认为整个图像矩形。

bins（灰度）或 l_bins/a_bins/b_bins（RGB565）设置每个通道的直方图分箱数。必须大于 2。默认为每个通道的最大分箱数。

difference 可以设置为一个图像对象，从而在不使用额外缓冲区的情况下，对当前图像与该图像之间的差进行操作。

不支持压缩图像或 bayer 图像。

get_statistics(thresholds: List[Tuple[int, int]] | None = None, invert: bool = False, roi: Tuple[int, int, int, int] | None = None, bins: int = -1, l_bins: int = -1, a_bins: int = -1, b_bins: int = -1, difference: Image | None = None) → statistics¶

对一个 roi 在所有颜色通道上计算均值、中值、众数、标准差、最小值、最大值、下四分位数和上四分位数，并返回一个 image.statistics 对象。也可通过 Image.get_stats() 或 Image.statistics() 调用。

thresholds 对于灰度图像是 (lo, hi) 元组的列表，对于 RGB565 图像是 (l_lo, l_hi, a_lo, a_hi, b_lo, b_hi) 元组的列表。如果传入，则仅在阈值内的像素上计算统计量。

invert 反转阈值匹配。

roi 是感兴趣区域矩形元组 (x, y, w, h)。默认为整个图像矩形。

bins（灰度）或 l_bins/a_bins/b_bins（RGB565）设置每个通道的直方图分箱数。必须大于 2。默认为每个通道的最大分箱数。

difference 可以设置为一个图像对象，从而在不使用额外缓冲区的情况下，对当前图像与该图像之间的差进行操作。

不支持压缩图像或 bayer 图像。

get_regression(thresholds: List[Tuple[int, int]], invert: bool = False, roi: Tuple[int, int, int, int] | None = None, x_stride: int = 2, y_stride: int = 1, area_threshold: int = 10, pixels_threshold: int = 10, target_size: Tuple[int, int] = (80, 60)) → line¶

对图像中所有阈值内的像素计算线性回归（Theil-Sen）。返回一个 image.line 对象，如果未找到直线则返回 None。

thresholds 对于灰度图像是 (lo, hi) 元组的列表，对于 RGB565 图像是 (l_lo, l_hi, a_lo, a_hi, b_lo, b_hi) 元组的列表。

invert 反转阈值匹配。

roi 是感兴趣区域矩形元组 (x, y, w, h)。默认为整个图像矩形。

x_stride 和 y_stride 控制在评估图像时跳过多少像素。

area_threshold 最小边界框面积；结果小于此值则返回 None。

pixels_threshold 最小阈值内像素数；结果小于此值则返回 None。

target_size 是一个 (w, h) 元组。ROI 在运行 O(N^2) 算法之前会被区域缩放到适合该尺寸之内。默认为 (80, 60)。

不支持压缩图像或 bayer 图像。

检测方法¶

find_blobs(thresholds: List[Tuple[int, int]], invert: bool = False, roi: Tuple[int, int, int, int] | None = None, x_stride: int = 2, y_stride: int = 1, area_threshold: int = 10, pixels_threshold: int = 10, merge: bool = False, margin: int = 0, threshold_cb: Callable | None = None, merge_cb: Callable | None = None, x_hist_bins_max: int = 0, y_hist_bins_max: int = 0) → List[blob]¶

在图像中查找所有色块（通过阈值测试的连通像素区域），并返回一个 image.blob 对象的列表。

thresholds 对于灰度图像是 (lo, hi) 元组的列表，对于 RGB565 图像是 (l_lo, l_hi, a_lo, a_hi, b_lo, b_hi) 元组（LAB 通道）的列表。最多可传入 32 个元组。min/max 值颠倒时会被自动修正；缺失的分量默认取最大范围。

invert 反转阈值匹配。

roi 是感兴趣区域矩形元组 (x, y, w, h)。默认为整个图像矩形。

x_stride 和 y_stride 控制在搜索色块时跳过多少像素。如果已知色块较大可增大该值。

area_threshold 最小边界框面积；更小的色块会被过滤掉。

pixels_threshold 最小阈值内像素数；更小的色块会被过滤掉。

merge 若为 True，则合并边界矩形相交的色块。margin 放大/缩小用于求交的边界矩形。被合并色块的 code 位向量会被逐位或在一起（每个阈值对应一位）。

threshold_cb 在阈值处理后对每个色块调用；返回 True 保留，返回 False 过滤。

merge_cb 对每一对即将合并的色块调用；返回 True 允许合并，返回 False 阻止合并。

x_hist_bins_max 若非零，则用这么多个分箱为每个色块填充一个 x_histogram 投影。

y_hist_bins_max 若非零，则用这么多个分箱为每个色块填充一个 y_histogram 投影。

不支持压缩图像或 bayer 图像。

find_lines(roi: Tuple[int, int, int, int] | None = None, x_stride: int = 2, y_stride: int = 1, threshold: int = 1000, theta_margin: int = 25, rho_margin: int = 25) → List[line]¶

使用霍夫变换在图像中查找所有无限长直线。返回一个 image.line 对象的列表。

roi 是感兴趣区域矩形元组 (x, y, w, h)。默认为整个图像矩形。

x_stride 和 y_stride 控制在霍夫变换期间跳过多少像素。

threshold 最小直线幅度（沿直线的 sobel 幅度之和）；低于此值的直线会被过滤掉。

theta_margin 和 rho_margin 控制合并：在这些阈值之内的直线会被合并。

不支持压缩图像或 bayer 图像。

此方法在 OpenMV Cam M4 上不可用。

find_line_segments(roi: Tuple[int, int, int, int] | None = None, merge_distance: int = 0, max_theta_difference: int = 15) → List[line]¶

在图像中查找线段。返回一个 image.line 对象的列表。

roi 是感兴趣区域矩形元组 (x, y, w, h)。默认为整个图像矩形。

merge_distance 是两条线段之间可被合并的最大像素间隔。

max_theta_difference 是两条线段之间可被合并的最大 theta 差（以度为单位）。

此方法在 OpenMV Cam M4 上不可用。

find_circles(roi: Tuple[int, int, int, int] | None = None, x_stride: int = 2, y_stride: int = 1, threshold: int = 2000, x_margin: int = 10, y_margin: int = 10, r_margin: int = 10, r_min: int = 2, r_max: int | None = None, r_step: int = 2) → List[circle]¶

使用霍夫变换在图像中查找圆。返回一个 image.circle 对象的列表。

roi 是感兴趣区域矩形元组 (x, y, w, h)。默认为整个图像矩形。

x_stride 和 y_stride 控制在霍夫变换期间跳过多少像素。

threshold 最小圆幅度（沿圆周的 sobel 幅度之和）；低于此值的圆会被过滤掉。

x_margin、y_margin 和 r_margin 控制合并：在这些阈值之内的圆会被合并。

r_min 最小圆半径。默认为 2。

r_max 最大圆半径。默认为 min(roi.w/2, roi.h/2)。

r_step 半径步长。默认为 2。

此方法在 OpenMV Cam M4 上不可用。

find_rects(roi: Tuple[int, int, int, int] | None = None, threshold: int = 1000) → List[rect]¶

使用 apriltag 四边形检测算法在图像中查找矩形。返回一个 image.rect 对象的列表。

roi 是感兴趣区域矩形元组 (x, y, w, h)。默认为整个图像矩形。

threshold 最小边缘幅度（沿矩形各边的 sobel 幅度之和）；低于此值的矩形会被过滤掉。

此方法在 OpenMV Cam M4 上不可用。

find_qrcodes(roi: Tuple[int, int, int, int] | None = None) → List[qrcode]¶

在 roi 内查找所有二维码，并返回一个 image.qrcode 对象的列表。

roi 是感兴趣区域矩形元组 (x, y, w, h)。默认为整个图像矩形。

此方法在 OpenMV Cam M4 上不可用。

在 roi 内查找所有 apriltag，并返回一个 image.apriltag 对象的列表。

roi 是感兴趣区域矩形元组 (x, y, w, h)。默认为整个图像矩形。

families 是要解码的标签家族的位掩码。它是以下各项的逻辑或：

image.TAG16H5

image.TAG25H9

image.TAG36H10

image.TAG36H11

image.TAGCIRCLE21H7

image.TAGCIRCLE49H12

image.TAGCUSTOM48H12

image.TAGSTANDARD41H12

image.TAGSTANDARD52H13

默认为 image.TAG36H11。检测时间随启用的家族数量而增加。

fx 和 fy 是摄像头的 X 和 Y 焦距（以像素为单位）。

cx 和 cy 是图像中心，通常为 image.width()/2 和 image.height()/2。

不支持压缩图像。

此方法在 OpenMV Cam M4 上不可用。

find_datamatrices(roi: Tuple[int, int, int, int] | None = None, effort: int = 200) → List[datamatrix]¶

在 roi 内查找所有 data matrix 码，并返回一个 image.datamatrix 对象的列表。

roi 是感兴趣区域矩形元组 (x, y, w, h)。默认为整个图像矩形。

effort 控制花费多少时间尝试查找 data matrix 匹配。值越高检测效果越好，但代价是帧率下降。低于约 160 的值会检测失败；高于约 240 的值收益递减。默认为 200。

此方法在 OpenMV Cam M4 上不可用。

find_barcodes(roi: Tuple[int, int, int, int] | None = None) → List[barcode]¶

在 roi 内查找所有一维条形码，并返回一个 image.barcode 对象的列表。会同时进行水平和垂直扫描。

支持的条形码类型：image.EAN2、image.EAN5、image.EAN8、image.UPCE、image.ISBN10、image.UPCA、image.EAN13、image.ISBN13、image.I25、image.DATABAR（RSS-14）、image.DATABAR_EXP（RSS-Expanded）、image.CODABAR、image.CODE39、image.PDF417、image.CODE93、image.CODE128。

roi 是感兴趣区域矩形元组 (x, y, w, h)。默认为整个图像矩形。

此方法在 OpenMV Cam M4 上不可用。

find_displacement(template: Image, roi: Tuple[int, int, int, int] | None = None, template_roi: Tuple[int, int, int, int] | None = None, logpolar: bool = False, fix_rotation_scale: bool = False) → displacement¶

使用相位相关法查找此图像相对于 template 的平移偏移。返回一个 image.displacement 对象。

roi 是感兴趣区域矩形 (x, y, w, h)。默认为整个图像矩形。

template_roi 是模板的感兴趣区域。默认为整个模板图像矩形。roi 和 template_roi 必须具有相同的宽度和高度。

logpolar 若为 True，则返回旋转/缩放变化，而非 x/y 平移。

fix_rotation_scale 若为 True，则在对齐旋转和缩放之后计算位移（仅当 logpolar=False 时有意义）。

备注

请在尺寸为 2 的幂的图像上使用此方法（例如 sensor.B64X64）。

不支持压缩图像或 bayer 图像。在 OpenMV Cam M4 上不可用。

find_template(template: Image, threshold: float, roi: Tuple[int, int, int, int] | None = None, step: int = 2, search: int = SEARCH_EX) → Tuple[int, int, int, int] | None¶

尝试使用归一化互相关在图像中查找 template 匹配的第一个位置。返回一个边界框元组 (x, y, w, h)，或 None。

template 是要与此图像匹配的灰度图像。

threshold 是一个值 (0.0-1.0)。较高的值会减少误报和检测；较低的值则相反。

roi 是感兴趣区域矩形元组 (x, y, w, h)。默认为整个图像矩形。

step 是搜索时跳过的像素数（仅在 image.SEARCH_EX 模式下使用）。

search 是 image.SEARCH_DS（更快的菱形搜索）或 image.SEARCH_EX（穷举搜索）。

仅适用于灰度图像。

find_features(cascade: Cascade, threshold: float = 0.5, scale: float = 1.5, roi: Tuple[int, int, int, int] | None = None) → List[Tuple[int, int, int, int]]¶

在图像中搜索与传入的 Haar 级联匹配的区域，并返回一个边界框元组 (x, y, w, h) 的列表。如果未找到特征，则返回空列表。

cascade 是一个 Haar 级联对象（参见 image.HaarCascade()）。

threshold (0.0-1.0)。较低的值会提高检测率和误报率。

scale 必须大于 1.0。较高的值运行更快，但产生的匹配效果较差。

roi 是感兴趣区域矩形元组 (x, y, w, h)。默认为整个图像矩形。

find_eye(roi: Tuple[int, int, int, int]) → Tuple[int, int]¶

在眼睛周围的感兴趣区域 (x, y, w, h) 元组内搜索瞳孔。返回瞳孔的 (x, y) 位置，如果未找到则返回 (0, 0)。

roi 是感兴趣区域矩形元组 (x, y, w, h)。

仅适用于灰度图像。

find_lbp(roi: Tuple[int, int, int, int]) → lbp_descriptor¶

从感兴趣区域提取 LBP（局部二值模式）关键点。使用 image.match_descriptor() 来比较两个描述符。

roi 是感兴趣区域矩形元组 (x, y, w, h)。

仅适用于灰度图像。

find_keypoints(roi: Tuple[int, int, int, int] | None = None, threshold: int = 20, normalized: bool = False, scale_factor: float = 1.5, max_keypoints: int = 100, corner_detector: int = CORNER_AGAST) → kp_descriptor | None¶

从感兴趣区域提取 ORB 关键点。使用 image.match_descriptor() 来比较两个描述符。如果未找到关键点则返回 None。

roi 是感兴趣区域矩形元组 (x, y, w, h)。默认为整个图像矩形。

threshold (0-255) 控制提取的角点数量。较低的阈值产生更多角点。AGAST 使用约 20，FAST 使用约 60-80。

normalized 若为 True，则禁用多分辨率关键点提取。

scale_factor 必须大于 1.0。较高的值运行更快，但产生的匹配效果较差。

max_keypoints 是要保留的最大关键点数量。

corner_detector 是 image.CORNER_FAST 或 image.CORNER_AGAST。

仅适用于灰度图像。

find_edges(edge_type: int, threshold: Tuple[int, int] = (100, 200)) → Image¶

将图像转为黑白，只留下边缘作为白色像素。

image.EDGE_SIMPLE - 简单的阈值化高通滤波器算法。

image.EDGE_CANNY - Canny 边缘检测算法。

threshold 是一个二值元组，包含一个低阈值和一个高阈值。你可以通过调整这些值来控制边缘的质量。它默认为 (100, 200)。

仅适用于灰度图像。

find_hog(roi: Tuple[int, int, int, int] | None = None, size: int = 8) → Image¶

用 HOG（方向梯度直方图）线条替换 ROI 中的像素。

roi 是感兴趣区域矩形元组 (x, y, w, h)。如果未指定，则等于整个图像矩形。只有 roi 内的像素会被操作。

仅适用于灰度图像。

此方法在 OpenMV Cam M4 上不可用。

stereo_disparity(reversed: bool = False, max_disparity: int = 64, threshold: int = 64) → Image¶

接受一幅双倍宽的灰度图像，其中包含两个并排摆放的摄像头传感器的输出，并将其中一半替换为立体视差图像（每个像素表示深度）。例如，对于两个 320x240 的摄像头，请传入一幅 640x240 的图像。

reversed 默认情况下将左图与右图比较并替换右图。设置为 True 可改为右图与左图比较并替换左图。

max_disparity 是使用绝对差之和搜索匹配像素块的最大距离 (1-255)。较大的值耗时呈指数级增长，但产生更高质量的输出。

threshold 如果两个块之间的绝对差之和小于或等于此阈值，则认为它们匹配。

selective_search(threshold: int = 500, size: int = 20, a1: float = 1.0, a2: float = 1.0, a3: float = 1.0) → List[Tuple[int, int, int, int]]¶

对图像运行选择性搜索，并返回一个目标候选框边界框元组 (x, y, w, h) 的列表。

threshold 是分割阈值；较高的值产生更少/更大的区域。

size 是合并后的最小区域大小。

a1、a2、a3 是合并区域时使用的颜色/纹理/大小相似度权重。