csi — 摄像头传感器

csi 是摄像头模块名，必须小写；CSI 是该模块中的类名，保持大写。导入写 import csi，创建摄像头写 cam = csi.CSI()，不要写成 import CSI 或 csi.csi()。

本页按 OpenMV H7 Plus、原配 OV5640、固件 5.0.1（OPENMV4P） 筛选。一个摄像头创建一个 CSI 实例，负责格式、分辨率、曝光、增益、白平衡、镜像及采集；snapshot() 返回 image.Image，后续再进行图像处理。

本模块接替旧 sensor 接口，不能直接混用旧的 sensor.set_*() 写法。

用法示例：

import csi

# 初始化摄像头
csi0 = csi.CSI()
csi0.reset()
csi0.pixformat(csi.RGB565)
csi0.framesize(csi.QVGA)
csi0.snapshot(time=2000)  # 持续采集并丢弃两秒内的图像

# 连续采图
while(True):
    csi0.snapshot()

csi.CSI() 创建对象，reset() 初始化传感器，接着设置 RGB565 彩色格式与 QVGA（320 × 240）分辨率。snapshot(time=2000) 让摄像头先稳定两秒；该调用结束后返回 None。循环中的无参数 snapshot() 才会返回每次采集的图像，需要处理时可写成 img = csi0.snapshot()。

Asyncio 用法

普通 snapshot() 会等待下一帧。在 asyncio 程序中，这段等待会阻止其他协程运行。需要让采图与串口、按钮或网络任务交替执行时，可以轮询 snapshot(blocking=False)，没有图像就通过 await asyncio.sleep_ms(0) 把执行机会交给其他任务。

import asyncio
import csi


class AsyncCSI:
    def __init__(self, *args, **kwargs):
        self._csi = csi.CSI(*args, **kwargs)

    def __getattr__(self, name):
        return getattr(self._csi, name)

    async def snapshot(self):
        while True:
            img = self._csi.snapshot(blocking=False)
            if img is not None:
                return img
            await asyncio.sleep_ms(0)

__getattr__ 将 reset、pixformat、framesize 等访问转交给内部的 CSI 对象。第一次非阻塞采集会在必要时启动摄像头的 DMA 采集，无需额外启动步骤。

下面是把适配器接入任务循环的片段，需要与上面的定义一起使用。some_other_task() 是原文中代表其他任务的名称，需要自行定义后才能运行整个示例。

async def capture_loop(cam):
    while True:
        img = await cam.snapshot()
        # 在这里处理图像

async def main():
    cam = AsyncCSI()
    cam.reset()
    cam.pixformat(csi.RGB565)
    cam.framesize(csi.QVGA)

    asyncio.create_task(some_other_task())
    await capture_loop(cam)

asyncio.run(main())

帧缓冲区数量仍会影响这一过程。单缓冲时，新帧尚未完成就返回 None；双缓冲或三缓冲可能已有完整帧等待读取。非阻塞采集让等待能够让出执行机会，并不使后续耗时的图像处理自动变成异步任务。

class CSI — 摄像头传感器接口

CSI 类用于控制一个摄像头传感器。以下签名中的 Optional[...] 表示允许 None，Tuple[...] 表示元组，List[...] 表示列表，箭头后是返回类型。类型标注用于查阅，实际调用时填写参数值。

CSI()

csi.CSI(cid:int=-1, delays:bool=True, fflush:bool=True, stream:Optional[bool]=None)

创建与摄像头通信的对象。

参数	含义
`cid`	传感器芯片 ID。H7 Plus 原配摄像头保持默认 `-1`，选择主传感器。
`delays`	默认 `True`，复位、模式切换后等待传感器稳定，避免读到异常帧。设为 `False` 可连续配置多个设置，但应在最终采图前自行留出稳定时间。
`fflush`	默认 `True`，启用驱动的自动帧缓冲区刷新。设为 `False` 取消帧缓冲 FIFO 中帧的自动时限。
`stream`	默认 `None`：只有主传感器自动成为 IDE 图像流来源。`True` 强制选择当前 CSI；其他假值保持已有图像流来源不变。

通常 H7 Plus 使用 cam = csi.CSI() 即可。具体芯片 ID 可以通过 csi.devices() 查询。

CSI.reset()

CSI.reset(hard:bool=True) -> None

初始化传感器。hard=True 时，通过摄像头 RESET 引脚执行硬件复位；与主摄像头共享 RESET 引脚的辅助传感器，应使用 hard=False，避免同时复位其他传感器。返回 None。

CSI.shutdown()

CSI.shutdown(enable:bool) -> None

enable=True 进入比 sleep() 更低功耗的关闭模式；False 退出。退出后需要调用 reset() 重新初始化。返回 None。

CSI.sleep()

CSI.sleep(enable:bool) -> None

enable=True 让摄像头进入睡眠，False 唤醒。返回 None。

CSI.flush()

CSI.flush() -> None

将当前帧缓冲区内容刷新到 IDE 预览。脚本准备结束时，可在最后一次 snapshot() 之后调用，使 IDE 显示最后一帧。返回 None。

CSI.snapshot()

CSI.snapshot(time:int=-1, frames:int=-1, blocking:bool=True, image:Optional[image.Image]=None) -> Optional[image.Image]

采集图像。普通调用返回 image.Image，可以继续调用图像对象的方法进行识别和绘制。

参数	行为
`time`	指定持续采集的时间，单位毫秒，用于等待画面稳定。
`frames`	指定采集并跳过的帧数。可与 `time` 同时使用。
`blocking`	默认 `True`，等待图像准备好；设为 `False` 时，尚无新帧就立即返回 `None`。
`image`	指定已有 `image.Image` 作为目标，将新图像深拷贝进去，覆盖原有内容。

指定 time 或 frames 后，等待相应采集过程结束，返回 None，不要将它当作图像使用。未指定跳帧参数时才按正常采图方式处理。本页 H7 Plus 原配组合使用手动镜像、翻转与转置，不依赖 IMU 自动旋转。

img = csi0.snapshot()
print(img.width(), img.height())

此片段接在初始化后运行。非阻塞方式需要先判断 img is not None，再访问图像。

CSI.width()

CSI.width() -> int

返回传感器当前输出图像的宽度，单位为像素，类型为 int。

CSI.height()

CSI.height() -> int

返回传感器当前输出图像的高度，单位为像素，类型为 int。

CSI.cid()

CSI.cid() -> int

返回摄像头模块的芯片 ID，类型为 int。可以与下方传感器 ID 常量比较，例如 csi.OV5640。该值表示传感器型号，不表示开发板型号。

CSI.readable()

CSI.readable() -> bool

有一帧可供 snapshot() 立即读取时返回 True；否则返回 False。可用来判断接下来的采图调用是否需要等待。

CSI.pixformat()

CSI.pixformat(pixformat:Optional[int]=None) -> Optional[int]

设置摄像头像素格式，可用 csi.GRAYSCALE、csi.RGB565、csi.BAYER、csi.YUV422，以及 OV2640／OV5640 支持的 csi.JPEG。无参数调用返回当前格式。

格式影响每帧内存占用和后续可用的图像算法。csi.BINARY 是可用于图像对象的常量，并不在本方法列出的摄像头采集格式中。详见像素格式常量。

CSI.framesize()

CSI.framesize(framesize:Optional[Union[int,Tuple[int,int]]]=None) -> Optional[int]

设置分辨率，可传入 csi.QVGA、csi.VGA 等分辨率常量，也可传入自定义 (w, h) 元组。

自定义尺寸在 snapshot() 时按 DMA 规则检查；通常涉及 8 像素或 16 字节的对齐要求，并非任意宽高都支持。无参数调用返回当前分辨率常量；自定义尺寸返回 csi.CUSTOM，实际宽高使用 width()、height() 读取。不要把 csi.CUSTOM 作为设置参数传回，应传入实际尺寸元组。

CSI.framerate()

CSI.framerate(rate:Optional[int]=None) -> Optional[int]

设置目标采集帧率，单位 Hz；无参数调用返回当前设置。

驱动通过丢弃帧，使输出帧率不超过目标值。默认按摄像头可达到的最高帧率运行；若传感器支持，也会降低内部采集帧率以节省功耗、增加可用曝光时间。部分传感器上可能与自动曝光冲突。

这里设置的是采集帧率上限，不是图像算法处理完后的实际循环帧率。

CSI.window()

CSI.window(roi:Optional[Union[Tuple[int,int],Tuple[int,int,int,int]]]=None) -> Optional[Tuple[int,int,int,int]]

在当前分辨率内设置输出窗口。roi=(x, y, w, h) 指定左上角及宽高；传入 (w, h) 时，窗口居中。无参数调用返回当前 (x, y, w, h)。

这会改变摄像头输出区域；只想限制某个检测算法搜索的区域时，应查看该算法的 roi 参数。

CSI.gainceiling()

CSI.gainceiling(gainceiling:int) -> bool

设置图像增益上限，可选 2、4、8、16、32、64、128。成功返回 True，失败返回 False。不要与 auto_gain() 中以 dB 表示的 gain_db_ceiling 混淆。

CSI.brightness()

CSI.brightness(brightness:int) -> bool

设置图像亮度。成功返回 True，失败返回 False。原文未给出所有传感器通用的数值范围，应按当前传感器支持情况使用。

CSI.contrast()

CSI.contrast(contrast:int) -> bool

设置图像对比度。成功返回 True，失败返回 False。原文未给出所有传感器通用的数值范围。

CSI.saturation()

CSI.saturation(saturation:int) -> bool

设置图像饱和度。成功返回 True，失败返回 False。原文未给出所有传感器通用的数值范围。

CSI.quality()

CSI.quality(quality:int) -> bool

设置摄像头输出 JPEG 的质量，范围为 0–100。仅适用于 OV2640／OV5640 摄像头。成功返回 True，失败返回 False。

CSI.colorbar()

CSI.colorbar(enable:bool) -> bool

True 开启传感器彩条测试图案，False 关闭；默认关闭。成功返回 True，失败返回 False。彩条可用来观察图像通路，与拍摄实际场景不同。

CSI.auto_gain()

CSI.auto_gain(enable:bool, gain_db:Optional[float]=None, gain_db_ceiling:Optional[float]=None) -> None

控制自动增益，摄像头启动时默认开启。

enable=False：关闭自动增益，可用 gain_db 指定固定增益，单位 dB。
enable=True：开启自动增益，可用 gain_db_ceiling 指定自动调节的最大增益，单位 dB。

返回 None。颜色跟踪通常还需要关闭自动白平衡，避免同一个物体在连续帧中的颜色随自动调节变化。

CSI.gain_db()

CSI.gain_db() -> float

返回当前摄像头增益，类型为浮点数，单位 dB。

CSI.auto_exposure()

CSI.auto_exposure(enable:bool, exposure_us:int=-1) -> None

控制自动曝光，摄像头启动时默认开启。enable=False 关闭后，可用 exposure_us 设置固定曝光时间，单位微秒。返回 None。

例如 exposure_us=10000 表示 10000 微秒，即 10 毫秒，不是 10000 毫秒。自动曝光算法通常对曝光时间的改动较保守，可能更多依靠增益来适应光照。

CSI.exposure_us()

CSI.exposure_us() -> int

返回当前曝光时间，类型为整数，单位微秒。

CSI.auto_whitebal()

CSI.auto_whitebal(enable:bool, rgb_gain_db:Optional[Tuple[float,float,float]]=None) -> None

控制自动白平衡，摄像头启动时默认开启。enable=False 时，可通过 rgb_gain_db=(r, g, b) 分别设置红、绿、蓝通道的固定增益，单位 dB。返回 None。

颜色跟踪通常还需要关闭自动增益。固定白平衡并不保证适应所有光照，阈值仍应在实际环境下调整。

CSI.rgb_gain_db()

CSI.rgb_gain_db() -> Tuple[float,float,float]

返回当前红、绿、蓝三个通道的增益，格式为 (r, g, b) 浮点数元组，单位 dB。

CSI.auto_blc()

CSI.auto_blc(enable:bool, regs:Optional[List[int]]=None) -> None

设置自动黑电平校准（BLC）。enable=True 开启，False 关闭；通常保持开启。关闭时可用 regs 设置寄存器值，该列表可以来自此前的 blc_regs()。返回 None。

CSI.blc_regs()

CSI.blc_regs() -> List[int]

返回当前传感器 BLC 寄存器值，类型为整数列表，可用于 auto_blc() 的 regs 参数。

CSI.hmirror()

CSI.hmirror(enable:Optional[bool]=None) -> Optional[bool]

True 开启水平镜像，False 关闭；默认关闭。不传参数时返回当前设置。

CSI.vflip()

CSI.vflip(enable:Optional[bool]=None) -> Optional[bool]

True 开启垂直翻转，False 关闭；默认关闭。不传参数时返回当前设置。

CSI.transpose()

CSI.transpose(enable:Optional[bool]=None) -> Optional[bool]

True 开启转置，False 关闭；默认关闭。不传参数时返回当前设置。转置可与镜像、翻转组合使用，原文给出的旋转对应关系如下。

`vflip`	`hmirror`	`transpose`	旋转角度
`False`	`False`	`False`	0°
`True`	`False`	`True`	90°
`True`	`True`	`False`	180°
`False`	`True`	`True`	270°

CSI.framebuffers()

CSI.framebuffers(count:Optional[int]=None) -> Optional[int]

设置接收图像使用的帧缓冲区数量。默认尝试分配能够容纳的最大数量；调用 pixformat()、framesize() 或 window() 时会重新分配。

`count`	模式
`1`	单缓冲
`2`	双缓冲
`3`	三缓冲
`4` 及以上	视频 FIFO 模式，按指定数量排队，适合向 SD 卡录制视频等场景

发生丢帧时，驱动清除活动缓冲区以外的帧，使 snapshot() 返回较新的图像。无参数调用返回当前缓冲区数量。构造函数的 fflush=False 会关闭自动刷新机制。

CSI.special_effect()

CSI.special_effect(effect:int) -> bool

设置数字效果：csi.NORMAL 为正常图像，csi.NEGATIVE 为反相效果。成功返回 True，失败返回 False。

CSI.lens_correction()

CSI.lens_correction(enable:bool, radi:int, coef:int) -> bool

控制传感器端镜头校正。enable 决定开关，radi 是待校正区域的整数像素半径，coef 是校正强度参数。成功返回 True，失败返回 False。

这是传感器端的校正，不是 image.Image.lens_corr()。OV5640 驱动只用 enable 切换传感器镜头校正位，radi、coef 保留在通用签名中但本驱动不使用；不要靠调整这两个参数调节 OV5640 的校正程度。

CSI.vsync_callback()

CSI.vsync_callback(cb:Optional[Callable[[int],None]]=None) -> Optional[Callable[[int],None]]

注册帧同步回调 cb：摄像头生成新帧时触发，此时整帧还未接收完成。回调在中断上下文执行，接收一个参数，表示变化后的 VSYNC 引脚状态。

无参数调用返回已注册回调；传入不可调用对象可清除回调，例如 cam.vsync_callback(False)。中断回调应尽量简短。

CSI.frame_callback()

CSI.frame_callback(cb:Optional[Callable[[],None]]=None) -> Optional[Callable[[],None]]

注册整帧接收完成的回调 cb，触发时图像已可通过 snapshot() 读取。回调在中断上下文执行，不接收参数。

可在回调内用 micropython.schedule() 安排后续读取，避免直接执行耗时图像处理。无参数调用返回已注册回调；传入不可调用对象可清除，例如 cam.frame_callback(False)。

CSI.ioctl()

CSI.ioctl(request:int, *args) -> Any

执行传感器专用控制命令。request 是 csi.IOCTL_* 常量，后续位置参数与返回值由具体命令决定。

下表中的调用形式省略了实例名和常量前缀。实际代码例如：cam.ioctl(csi.IOCTL_GET_READOUT_WINDOW)。同一模块列出多种传感器的命令，不代表当前摄像头支持全部命令。

OV5640 读出窗口与夜间模式

调用形式	参数与返回值
`ioctl(IOCTL_SET_READOUT_WINDOW, (x, y, w, h))`	设置传感器读出窗口，也接受 `(w, h)`；较小窗口可能提高帧率，同时减少视野。
`ioctl(IOCTL_GET_READOUT_WINDOW)`	返回当前读出窗口 `(x, y, w, h)`。
`ioctl(IOCTL_SET_NIGHT_MODE, enable)`	开启或关闭夜间模式，以较低帧率换取更长曝光。
`ioctl(IOCTL_GET_NIGHT_MODE)`	返回夜间模式状态，类型为 `bool`。

原配镜头不按带自动对焦机构的 OV5640 FPC 模组处理；IOCTL_*_AUTO_FOCUS 不列为本页用法。其他传感器的触发、视野优先、通道统计及热成像命令也不混入此表。

CSI.__write_reg()

CSI.__write_reg(address:int, value:int) -> None

向传感器地址为 address 的寄存器写入 value。返回 None。地址与数值含义需查对应摄像头数据手册。

CSI.__read_reg()

CSI.__read_reg(address:int) -> int

读取传感器地址为 address 的寄存器，返回整数。寄存器含义需查对应摄像头数据手册。

模块函数

csi.devices()

csi.devices() -> List[int]

返回检测到的传感器芯片 ID 列表。它是模块级函数，直接调用 csi.devices()，不需要通过某个 CSI 实例调用。

常量

下面保留本页用到的常量，使用 csi. 前缀并保持官方大写。

像素格式

常量	说明
`csi.BINARY`	二值位图，每像素 1 bit，适合掩码存储，可用于 `image.Image()`。
`csi.GRAYSCALE`	灰度格式，来自 YUV422 的 Y 通道，每像素 8 bit。
`csi.RGB565`	彩色格式，每像素 16 bit：红色 5 bit、绿色 6 bit、蓝色 5 bit。
`csi.BAYER`	传感器原始 Bayer 格式。
`csi.YUV422`	Y1、U、Y2、V 交替存储，两个亮度像素共享色度信息；只有部分图像方法支持。
`csi.JPEG`	摄像头直接输出压缩 JPEG，使用 `CSI.quality()` 设置质量，仅适用于 OV2640／OV5640。

传感器 ID

常量	说明
`csi.OV5640`	原配 OV5640 的芯片 ID，可与 `cam.cid()` 返回值比较。

图像效果

常量	说明
`csi.NORMAL`	正常图像效果，用于 `CSI.special_effect()`。
`csi.NEGATIVE`	反相效果，用于 `CSI.special_effect()`。

分辨率

常量	说明
`csi.CUSTOM`	自定义分辨率的返回标识。设置分辨率时传 `(w, h)`，不能传此常量。
`csi.QCIF`	176 × 144 像素。
`csi.CIF`	352 × 288 像素。
`csi.QSIF`	176 × 120 像素。
`csi.SIF`	352 × 240 像素。
`csi.QQQVGA`	80 × 60 像素。
`csi.QQVGA`	160 × 120 像素。
`csi.QVGA`	320 × 240 像素。
`csi.VGA`	640 × 480 像素。
`csi.HQVGA`	240 × 160 像素。
`csi.HVGA`	480 × 320 像素。
`csi.SVGA`	800 × 600 像素。
`csi.XGA`	1024 × 768 像素。
`csi.SXGA`	1280 × 1024 像素，仅适用于 OV2640／OV5640。
`csi.UXGA`	1600 × 1200 像素，仅适用于 OV2640／OV5640。
`csi.HD`	1280 × 720 像素。
`csi.FHD`	1920 × 1080 像素，仅适用于 OV5640。
`csi.QHD`	2560 × 1440 像素，仅适用于 OV5640。
`csi.QXGA`	2048 × 1536 像素，仅适用于 OV5640。
`csi.WQXGA`	2560 × 1600 像素，仅适用于 OV5640。
`csi.WQXGA2`	2592 × 1944 像素，仅适用于 OV5640。

传感器控制命令

这些命令通过 CSI.ioctl() 调用，完整参数和返回值见该方法。

常量	说明
`csi.IOCTL_SET_READOUT_WINDOW`	设置传感器读出窗口。
`csi.IOCTL_GET_READOUT_WINDOW`	读取传感器读出窗口。
`csi.IOCTL_SET_NIGHT_MODE`	设置夜间模式，通过降低帧率增加曝光时间。
`csi.IOCTL_GET_NIGHT_MODE`	读取夜间模式状态。

本板范围

H7 Plus 原配组合不具备本页所需的板载 IMU 自动旋转条件；手动旋转使用上面的 transpose()、hmirror()、vflip()。需要更换传感器、自动对焦模组或增加外部硬件时，再查官方相应专用接口，不把它们视为原配功能。

Asyncio 用法​

class CSI — 摄像头传感器接口​

CSI()​

CSI.reset()​

CSI.shutdown()​

CSI.sleep()​

CSI.flush()​

CSI.snapshot()​

CSI.width()​

CSI.height()​

CSI.cid()​

CSI.readable()​

CSI.pixformat()​

CSI.framesize()​

CSI.framerate()​

CSI.window()​

CSI.gainceiling()​

CSI.brightness()​

CSI.contrast()​

CSI.saturation()​

CSI.quality()​

CSI.colorbar()​

CSI.auto_gain()​

CSI.gain_db()​

CSI.auto_exposure()​

CSI.exposure_us()​

CSI.auto_whitebal()​

CSI.rgb_gain_db()​

CSI.auto_blc()​

CSI.blc_regs()​

CSI.hmirror()​

CSI.vflip()​

CSI.transpose()​

CSI.framebuffers()​

CSI.special_effect()​

CSI.lens_correction()​

CSI.vsync_callback()​

CSI.frame_callback()​

CSI.ioctl()​

OV5640 读出窗口与夜间模式​

CSI.__write_reg()​

CSI.__read_reg()​

模块函数​

csi.devices()​

常量​

像素格式​

传感器 ID​

图像效果​

分辨率​

传感器控制命令​

本板范围​