[具身智能-634]：Python 封装的地平线 VIO 多媒体库：libsrcampy库详解

srcampy /libsrcampy 名称释义先明确结论官方文档没有公布标准化英文全称是地平线内部项目缩写行业公认拆解如下srcampy Source Amplifier Python bindingsrc Source图像源MIPI Sensor、视频源amp Amplifier引申VSP/VPU 图像信号处理流水线 ISP 放大器通道内部代号AMP指代地平线多媒体图像流水线py Python bindingC 库对外 Python 封装底层库文件名libsrcamp.soPython 封装后命名libsrcampy代码内导入别名srcampy。补充背景RDK 平台内部代号地平线 RDK X3/X5多媒体驱动内部存在AMP Pipeline AMP Advanced Multimedia Pipeline高级多媒体流水线 负责MIPI 接收 → ISP 处理 → 多路缩放 → 编码 → 显示通路。这是amp词根真正来源。完整合理全称Source Advanced Multimedia Pipeline Python API中文理解图像源多媒体流水线 Python 接口库。不要混淆和音频 amplifier 功放无关属于图像 ISP 流水线代号不是Sample、Stream之类缩写区分libsrcamp.so原生 C 多媒体库libsrcampy.soC 库 Python 包装层 → 代码from hobot_vio import libsrcampy极简一句话记忆src图像源 amp多媒体流水线 AMP pyPython 封装 srcampy顺带区分配套名词方便你整体理解hobot_vioVIO Video Input Output视频输入输出包名libsrcampyVIO 包里面负责操控摄像头、HDMI、硬件数据流绑定的核心模块。srcampylibsrcampy完整详解一、基础定位python运行try: from hobot_vio import libsrcampy as srcampy except ImportError: from hobot_vio_rdkx5 import libsrcampy as srcampy全称libsrcampyPython 封装的地平线 VIO多媒体库平台区分RDK X3包名hobot_vioRDK X5包名hobot_vio_rdkx5核心用途专门操控 MIPI CSI 摄像头、ISP 图像流水线、HDMI 显示、硬件绑定数据流、OSD 图层叠加⚠️最重要区别只用于板载 MIPI 相机不用于 USB 摄像头不兼容标准 V4L2 /cv2.VideoCapture不要混用底层调用地平线自研 ISP 驱动不是 Linux 通用 uvc 驱动底层硬件流水线FCOS 代码的完整链路plaintextMIPI Sensor → ISP硬件流水线(VPS) → 多路硬件缩放输出 ├─通路A原始分辨率 → 直通HDMI └─通路B模型输入尺寸(NV12) → Python读取送给BPU推理所有缩放、格式转换由硬件 ISP 完成几乎不占用 CPU。二、srcampy 四大核心类Camera/Display/Encoder/DecoderFCOS 代码只用到前两个。1. srcampy.Camera () — MIPI 摄像头采集类1.1 cam.open_cam () 【重中之重】函数原型RDK X5 标准python运行cam.open_cam(video_index, fps, [out_w1, out_w2], [out_h1, out_h2], sensor_h, sensor_w)对应你代码python运行cam.open_cam(0, -1, -1, [w, disp_w], [h, disp_h], sensor_height,sensor_width)逐个参数拆解RDK X5 专属规则表格参数含义说明video_indexMIPI CSI 硬件通道 IDCSI0 → 0CSI1 → 2不是 1fps帧率-1 使用传感器默认帧率通常 30fps[out_w1, out_w2]两路输出宽度数组ISP硬件双通路输出[out_h1, out_h2]两路输出高度数组通路 1模型输入尺寸通路 2HDMI 预览尺寸sensor_h / sensor_wSensor 原生分辨率IMX415/IMX477 常用1080/1920双通路含义 ISP 硬件同时生成两张 NV12 图像通路 1w × h512×512→ 送给 FCOS 模型推理通路 2disp_w × disp_h1920×1080→ 送到 HDMI 实时预览全程硬件缩放无 CPU 图像 resize1.2 cam.get_img()python运行img cam.get_img(2, 512, 512)参数 1图像格式编号2 NV12模型需要的格式参数 2/3读取哪一路通路的分辨率返回值bytes 裸缓冲区NV12 内存数据python运行# 转为numpy数组 img np.frombuffer(img, dtypenp.uint8)✅巨大优势 拿到直接可用的 NV12不需要运行bgr2nv12_opencv()省去大量 CPU 运算。1.3 cam.close_cam()释放 ISP、MIPI 通道资源程序退出必须调用否则下次打开摄像头失败。1.4 常见坑CSI1 通道必须写video_index2填 1 直接识别不到摄像头open_cam两路分辨率顺序必须和get_img匹配不能同时用 srcampy v4l2-ctl/cv2.VideoCapture 读取同一个 CSI 通道驱动互斥抢占2. srcampy.Display () — HDMI 显示 OSD 图层类2.1 disp.display(layer_id, w, h)切换显示图层python运行# layer 0原始视频画面图层摄像头直通画面 disp.display(0, disp_w, disp_h) # layer 3OSD图形叠加图层绘制框、文字 disp.display(3, disp_w, disp_h)图层规则Layer0原始视频流Layer3OSD 叠加层透明图层用于绘制检测框OSD 图层不会修改原始视频流只是硬件叠加渲染CPU 开销极低。2.2 srcampy.bind(cam, disp)python运行srcampy.bind(cam, disp)硬件通路绑定把 Camera ISP 输出的原始分辨率图像直接硬件路由到 HDMI 显示。 画面传输完全不走 Python 内存零拷贝、极低延迟主线程不需要转发图像给显示器。2.3 OSD 绘图 API代码绘制检测框核心disp.set_graph_rect(x1,y1,x2,y2,line_width,refresh_flag, ARGB_color)绘制矩形框目标检测框disp.set_graph_word(x,y,text_bytes,font_size,refresh_flag, ARGB_color)绘制文字类别 置信度refresh_flag0 / 1关键说明1刷新整个 OSD 画布清空上一轮所有框0增量绘制不清空画布代码逻辑第一个目标使用 flag1 清空旧框后续目标 flag0 叠加绘制ARGB 颜色格式python运行box_color_ARGB 0xFF000000 | R16 | G8 | B最高字节 Alpha (FF 不透明)依次 R、G、B。2.4 disp.get_display_res()查询 HDMI 显示器支持的分辨率列表用于自动适配防止黑屏。python运行resolution_list disp.get_display_res()2.5 disp.close()释放显示硬件资源。3. 全局接口 srcampy.bind ()python运行srcampy.bind(源对象, 目标对象)支持绑定组合Camera → Display摄像头直通 HDMI 预览Camera → Encoder摄像头图像直接送入硬件 H.264/H.265 编码器录像 数据流走硬件 DMA不经过用户内存极致低延迟。三、srcampy 完整流水线对照你的 FCOS 代码plaintext1. cam.open_cam() → 启动MIPI CSI0开启ISP双通路硬件缩放 2. disp.display(0) → 打开视频图层 3. srcampy.bind(cam, disp) → 原始画面硬件直通HDMI 4. disp.display(3) → 切换到OSD绘图图层 循环 cam.get_img(2,512,512) → 获取ISP输出512×512 NV12 buffer models[0].forward(img) → BPU FCOS推理 多进程执行后处理 → 解码检测框 → disp.set_graph_rect / set_graph_word 在OSD图层绘制框四、srcampy 优势对比 cv2.VideoCapture表格特性srcampy (MIPI 专用)cv2.VideoCapture(V4L2)图像来源MIPI CSI 摄像头USB 摄像头RDK MIPI原生不支持图像格式直接输出 NV12只能读取 BGR/YUYV缩放操作ISP 硬件缩放零 CPUCPU resize占用算力直通 HDMI硬件 bind极低延迟软件转发延迟高OSD 叠加硬件图层绘制性能高需要 CPU 逐帧绘制图像多路输出支持同时输出多路分辨率单路输出五、高频踩坑清单工程调试重点CSI1 通道 video_index2不要写 1最常见错误cam.get_img(2,w,h)分辨率必须和 open_cam 通路匹配否则返回空OSD 图层绘制多进程并发容易闪烁建议收敛到同一个进程绘制程序异常退出务必调用cam.close_cam()否则 ISP 卡死重启才能恢复bind 之后原始画面不再经过 PythonPython 只能读取第二路推理尺寸图像NV12 是 packed 格式不要错误当作 RGB 处理HDMI 热插拔后需要重新执行get_display_res()刷新分辨率六、拓展能力你现有代码没有用到srcampy.Encoder()硬件 H.264/H.265 编码直接把摄像头 NV12 流转码保存视频无需 CPU 编码。python运行enc srcampy.Encoder() enc.encode(0, width, height)srcampy.Decoder()硬件解码 H264/H265 码流输出 NV12 图像送入 BPU 推理。七、最简使用模板单路 CSI0 摄像头python运行from hobot_vio_rdkx5 import libsrcampy as srcampy import numpy as np sensor_w, sensor_h 1920,1080 model_w, model_h 512,512 preview_w, preview_h 1920,1080 cam srcampy.Camera() # CSI0 0CSI1 2 cam.open_cam(0, -1, -1, [model_w, preview_w], [model_h, preview_h], sensor_h, sensor_w) disp srcampy.Display() disp.display(0, preview_w, preview_h) srcampy.bind(cam, disp) disp.display(3, preview_w, preview_h) while True: nv12_buf cam.get_img(2, model_w, model_h) frame np.frombuffer(nv12_buf, dtypenp.uint8) # frame 直接送入dnn forward推理 cam.close_cam() disp.close()