1. 功能库先跑通:UVC 摄像头从探测到出图的完整链路
板端接上 USB 摄像头,想不写底层驱动就把画面送到屏幕,最直接的入口是媒体功能库里的 UVC 摄像头链路。它把 media.display、media.media、media.uvc 和 nonai2d.CSC 串在 Python 层,显示初始化、媒体缓冲区管理、摄像头探测、视频模式协商、抓帧、色彩转换和资源释放都能按顺序调用。对刚接手板端视觉采集的人,这套功能库最大的价值是先把“摄像头能不能出图”验证掉,而不是一上来啃驱动。
它适合刚拿到板子、要用 USB 摄像头做快速原型的人,也适合在调显示或图像链路、想找一个可重复最小闭环的人。前提是 UVC 摄像头被系统识别、视频模式能协商成功、显示和媒体缓冲区先初始化。下面按能跑通的顺序写,先把最小链路立住,再谈参数和踩坑。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 功能库初始化:显示、媒体管理与 CSC 的启动顺序
2.1 先初始化显示和媒体管理器
初始化段不是把几个 import 堆在一起就完事,它决定了后面 UVC.start 有没有可用的显示设备和媒体缓冲区。按这条链路,先配置显示,再初始化媒体管理器,最后创建 CSC 转换通道。显示初始化负责把画面送到屏幕,MediaManager.init 负责把媒体数据链路和缓冲区准备好,CSC 负责后面把摄像头帧转成显示能接收的像素格式。
python复制import time
import gc
from media.display import *
from media.media import *
from media.uvc import *
from nonai2d import CSC
DISPLAY_WIDTH = ALIGN_UP(800, 16)
DISPLAY_HEIGHT = 480
Display.init(Display.ST7701, width = DISPLAY_WIDTH, height = DISPLAY_HEIGHT, to_ide = True)
MediaManager.init()
csc = CSC(0, CSC.PIXEL_FORMAT_RGB_565)
这段代码先解决显示和缓冲区,再创建转换通道。参数上,DISPLAY_WIDTH 用 ALIGN_UP(800, 16),意思是把宽度按 16 对齐后再交给显示初始化;800 本身是 16 的倍数,所以最终宽度还是 800,但写成对齐表达式,后面改分辨率时不容易漏掉对齐要求。DISPLAY_HEIGHT 直接给 480。Display.init 里的 Display.ST7701 是显示设备枚举,to_ide=True 表示同时往 IDE 输出预览,调试阶段保留它,能多一个观察窗口。
注意:改 DISPLAY_WIDTH 时不要只把 800 换成别的数,ALIGN_UP 的对齐值也要一起确认,否则显示链路可能先栽在行宽对齐上。
| 参数/调用 | 代码里的值 | 作用 | 改动时注意 |
|---|---|---|---|
| DISPLAY_WIDTH | ALIGN_UP(800, 16) | 显示宽,按 16 对齐 | 改分辨率时保留对齐表达式 |
| DISPLAY_HEIGHT | 480 | 显示高 | 和屏的实际能力对齐 |
| Display.ST7701 | 显示设备枚举 | 指定显示设备 | 按实际屏改,不要照抄 |
| to_ide | True | 同时输出到 IDE 预览 | 调试保留,稳定后再决定 |
| CSC 通道 | 0 | 转换通道编号 | 多路转换时再区分 |
| CSC 格式 | PIXEL_FORMAT_RGB_565 | 转换目标像素格式 | 和显示链路一起改 |
这张表里最容易被忽略的是 CSC 格式。它不是“随便填一个就行”的参数,后面 csc.convert 会按这里的目标格式输出,Display.show_image 再接这个结果。初始化阶段先把 RGB_565 固定住,是为了让整条链路只有一个色彩格式变量。
2.2 CSC 通道和显示格式要对齐
CSC(0, CSC.PIXEL_FORMAT_RGB_565) 有两个参数:第一个 0 是转换通道,第二个是目标像素格式。转换通道先给 0,是因为这条最小链路只有一路摄像头输入;目标格式给 RGB_565,是为了让 convert 的输出直接进入显示。RGB_565 从名字就能看出是 5-6-5 的 16 位排列,显示链路用这种格式能少占带宽和缓冲区,但前提是后面 show_image 接收的也是这个结果。
这里最常见的误用是只改一边:有人把 CSC 初始化改成别的像素格式,却忘了 convert 之后的显示路径还按 RGB_565 在跑;也有人反过来,显示换了格式,CSC 还留在 RGB_565。两边不一致时,画面可能颜色不对、发灰,甚至显示异常。第一次跑通不要同时改这两个地方,先把例子里的一组固定组合跑出来,再谈替换。
从选型理由看,这条链路先用 640×480 的摄像头输出、800×480 的显示输出、RGB_565 的转换目标,是为了把“采集分辨率”和“显示分辨率”分开。采集端不必强行等于显示端,显示端也不必反向约束摄像头。后面调画面大小时,先动 video_mode 的采集参数,再决定要不要动显示分辨率,不要把两个变量一起改。
2.3 初始化阶段的检查点
初始化段跑完,先别急着接摄像头。我一般先确认三件事:显示初始化没有报错,MediaManager.init 已经执行,CSC 对象已经创建。这三步对应后面的三条依赖:没有显示,show_image 没地方落;没有媒体管理器,UVC.start 没有缓冲区;没有 CSC,convert 没有转换通道。
第二个检查点是顺序。代码里是 Display.init → MediaManager.init → CSC 创建,后面才是 UVC.probe 和 UVC.start。这个顺序不要倒过来,尤其不要把 UVC.start 提到 MediaManager.init 前面。UVC.start 一旦先跑,后面再补媒体管理器,轻则启动失败,重则资源状态不干净,下一次运行还得先解决残留问题。
第三个检查点是分辨率。DISPLAY_WIDTH 和 DISPLAY_HEIGHT 是显示分辨率,不是摄像头采集分辨率。摄像头采集分辨率在下一章的 UVC.video_mode(640, 480, ...) 里。把这两个概念混在一起,会出现“明明改了显示宽,摄像头画面还是原来大小”的错觉。显示端改的是画布,采集端改的是输入,二者不是同一个参数。
初始化段单独跑通后,再进入设备探测。这样一旦后面出问题,能快速判断是显示和缓冲区没准备好,还是摄像头没被识别。血泪经验是:不要一上来就把初始化、探测、取流、释放全塞进一个大循环,出错时根本看不出是哪一段先翻车。
3. 功能库设备协商:probe、video_mode 与 select_video_mode
3.1 用 UVC.probe 轮询确认设备在线
设备探测放在初始化之后、取流之前。UVC.probe 返回两个值:plugin 和 dev。plugin 为真表示检测到摄像头,dev 是设备信息;plugin 为假时不要继续往下走,因为后面的 video_mode 和 select_video_mode 都建立在“设备在线”这个前提上。
python复制while True:
plugin, dev = UVC.probe() # 检测 USB 摄像头
if plugin:
print(f"detect USB Camera {dev}")
break
else:
print(f"error USB Camera {dev}")
time.sleep_ms(100)
这段轮询的逻辑很直白:检测到就打印设备信息并跳出循环,检测不到就打印错误并等 100ms 再试。100ms 是材料里给出的轮询间隔,不要改成忙等,也不要在 error 分支里直接往下执行。当前这条 UVC 功能库只支持单个摄像头检测,所以接多个摄像头时不要指望它帮你选出“正确的那一个”,先保证只接一个。
调试时这行打印很关键。它相当于整条链路的第一块黑匣子:看到 detect USB Camera 后面的 dev,说明设备至少被识别了;一直看到 error USB Camera,就先查线、查口、查摄像头本身,不要急着改 video_mode。设备都没上线,后面参数怎么调都是空转。
3.2 video_mode 的四个参数怎么定
探测通过后,下一步是构造并选择视频模式。材料里给的请求是 640×480、MJPEG、30 帧。这四个参数分别对应采集宽、采集高、摄像头输出格式和请求帧率。注意 MJPEG 是摄像头输出格式,不是最终显示格式;显示前还要经过 CSC 转成 RGB_565。
python复制mode = UVC.video_mode(640, 480, UVC.FORMAT_MJPEG, 30) # 构造视频模式
succ, mode = UVC.select_video_mode(mode) # 设置摄像头输出模式
print(f"select mode success: {succ}, mode: {mode}")
这段代码先构造模式,再让功能库去协商,最后把协商结果打印出来。参数上,640×480 是采集分辨率,显示端是 800×480,所以画面不会刚好铺满整个显示宽度;第一次跑通先接受这个差异,先保证链路通,再考虑采集和显示的比例问题。MJPEG 适合先跑通,是因为摄像头端先输出压缩帧,功能库再处理,链路变量少。30 是请求帧率,实际以 select_video_mode 返回的 mode 为准,不要拿代码里写的 30 当承诺。
| 参数 | 代码里的值 | 含义 | 调整时先看什么 |
|---|---|---|---|
| 采集宽 | 640 | 摄像头输出宽度 | 摄像头是否支持该宽度 |
| 采集高 | 480 | 摄像头输出高度 | 摄像头是否支持该高度 |
| 输出格式 | UVC.FORMAT_MJPEG | 摄像头输出 MJPEG | 换格式后 CSC 是否还能接 |
| 请求帧率 | 30 | 期望帧率 | 返回 mode 里的实际帧率 |
这张表里没有“必须用 640×480”的结论,只有“先把这组写死,减少变量”的做法。第一次调功能库最怕一次改五个参数,最后不知道哪个参数造成的变化。先把采集参数固定,显示参数固定,CSC 固定,跑通后再逐个替换。
3.3 succ 和 mode 要打印,不要静默
select_video_mode 返回 succ 和 mode,一个表示选择是否成功,一个表示实际选中的模式。材料里直接 print 这两个值,这个习惯要保留。很多人只写 succ, mode = UVC.select_video_mode(mode) 就继续往下跑,结果 succ 为假时主循环一直拿不到帧,还以为是 snapshot 的问题。
看到 succ 为真,至少说明模式协商这一步过了;看到返回的 mode 和请求不一致,也不要惊讶,摄像头可能按自己的能力选了最接近的组合。这时要做的是根据打印结果调整请求,而不是把打印删掉假装没发生。我一般会把这一行保留到链路稳定,再决定是否收进日志。
如果 succ 为假,先回到 probe:设备在线吗?再检查 video_mode 的四个参数是不是摄像头不支持的组合。不要在主循环里加重试去掩盖协商失败,协商失败和偶发丢帧不是一类问题,前者应该在启动阶段解决。
3.4 UVC.start 的位置和 cvt 参数
模式协商成功后,才启动视频流。材料里的顺序是 select_video_mode 之后执行 UVC.start(cvt = True),然后初始化 clock。这个顺序不要反:先 start 再 select,相当于流已经开了但模式还没定;先 start 再 probe,设备都没确认,启动没有意义。
python复制UVC.start(cvt = True) # 开始摄像头视频流输出
clock = time.clock()
cvt=True 先按材料里的值跑通。可以把它理解为启动时让功能库接管转换链路,第一次调试不要把它关掉,除非你已经单独验证过 convert 和显示路径能独立工作。clock 放在 start 后面,是为了后面主循环里用 clock.tick 和 clock.fps 观察节拍,不要把它当成摄像头帧率配置。
启动之后不要立刻塞入耗时操作。start 和主循环之间只留 clock 初始化,能让第一帧尽快进来。如果 start 后先做了别的初始化,第一帧可能晚到,调试时容易误
