从一帧图像到实时视频启元 Q1 的视觉数据架构写在最前面1 按需抓拍与连续视频怎样分工2 一次抓拍怎样交付图像和采集信息3 连续视频怎样变成算法可用的图像3.1 RTSP 入口与客户端视频后端3.2 网络媒体流与本地录像的表示不同4 取流与模型推理怎样各自推进5 怎样读懂帧率和时延6 沿数据通路定位问题与扩展能力参考资料启元机器人开发者社区你好这里是 晓雨的笔记本在所有感兴趣的领域扩展知识感谢你的陪伴与支持~ 欢迎添加好友 is_yu_ei不定期掉落福利资讯写在最前面版权声明本文为原创技术架构解读遵循 CC 4.0 BY-SA 协议。转载请注明出处。文章依据启元 Q1 SDK v1.0.0.0 公开接口说明与 Python 示例梳理重点是单帧 JPEG 抓拍和 RTSP 连续视频两条视觉数据通路。同样使用机器人摄像头拍一张桌面照片、持续显示现场画面、让视觉模型定期识别物体对数据的要求并不相同。抓拍需要一次完整响应预览希望不断得到新画面模型推理则需要与自身处理速度相适应的输入。把它们接到一起之前首先要看清图像经过了哪些模块。启元 Q1 的公开 SDK 给出了两条视觉入口通过 ROS 2 服务获取单帧 JPEG以及通过 RTSP 读取连续视频。沿着这两条通路可以进一步理解图像采集、网络传输、客户端解码与应用消费之间的分工。本文以 Q1 SDK v1.0.0.0 的接口和示例为依据分析一个视觉应用如何从“拿到画面”发展为有清楚职责划分的数据系统。[1] [2]图1 启元 Q1 的两条视觉数据通路。抓拍服务的响应直接携带 JPEG连续视频由 RTSP 入口和客户端视频后端衔接。依据 SDK 接口与示例绘制表示公开访问关系。[2]1 按需抓拍与连续视频怎样分工Q1 的视觉采集管理章节列出了交互相机标识为 head_monocular_centra。同一相机可以面向不同的使用节奏提供数据程序偶尔需要一张图时调用 CaptureJpegImage应用需要连续画面时访问相应的 RTSP 地址。[2]抓拍服务围绕一次请求工作。调用者指定相机服务等待图像并把 JPEG 数据连同元信息返回。连续视频则建立持续读取通路由客户端的视频后端接收和解码应用循环取得图像帧。图1把两种交互方式放在一起入口的差别也对应着后续程序组织方式的差别。接口说明建议单帧抓拍按约 1 fps 的节奏使用并在一次响应结束后再发起下一次调用更高频的连续图像需求转向 RTSP。这里的 1 fps 是文档使用建议适合用来选择入口。对开发者而言一张按需获取的照片与一段持续更新的视频可以各自承担清楚的职责。[2]例如资料采集程序可以在用户需要时保存一张 JPEG远程观察程序可以持续读流视觉分析模块则从连续帧中选择适合自己的输入。这种分工使取图方式与应用需求对应起来也为后续的预览、推理和录像提供了不同的组织空间。2 一次抓拍怎样交付图像和采集信息单帧入口的完整服务名是 /aima/hal/camera/CaptureJpegImage。请求包含 camera_id、timeout_ms 和公共请求头响应包含公共响应信息与 JpegImage 包装体。图像直接位于响应中因此这个服务同时完成请求交互和图像数据交付。[2]JpegImage 提供的不只是图片内容。camera_id 标明来源width 和 height 描述尺寸exposure、gain 等字段保留采集条件image 则采用 sensor_msgs/CompressedImage 承载压缩图像。把这些信息随图片一并保存后续才能解释同一识别程序为什么可能收到尺寸、亮度或来源不同的输入。[2]表1 一次 JPEG 响应中各组信息的职责字段或内容对应含义应用中的用途camera_id、device相机来源与设备信息将图片和正确的数据源关联width、height图像尺寸安排解码后的缩放与模型输入处理framerate、exposure、gain返回的采集元信息记录与解释采集条件image.format、image.data压缩格式与 JPEG 字节保存图片或解码为像素后交给算法字段依据 JpegImage.msg 与接口说明右列为相应应用用途。元信息字段用于描述此次返回的数据。[2]官方 get_jpg.py 示例展示了一个很直接的数据交接从 response.jpeg.image.data 取得字节检查内容非空再写入 JPEG 文件。保存模块面对的是完整的 JPEG 载荷如果后续模块接收的是像素数组还需要在接口之间加入 JPEG 解码和模型要求的预处理。[2]超时也有各自负责的阶段。服务请求中的 timeout_ms 控制等待新帧的最长时间设为 0 时接口文档给出的服务端默认值是 1000 ms。客户端等待整个调用返回还要覆盖通信和响应处理所以示例另设了调用等待时间。把这两个时间分开才容易判断问题发生在等待图像还是等待服务响应的过程中。[2]这条通路适合把“获取一张图片”封装成一个独立能力。上层只需要选择相机和等待策略图像服务负责返回图片保存或识别模块继续处理自己需要的数据形态。曝光和增益等信息在这里作为返回值使用需要调整采集参数时应继续查找对应的控制接口。3 连续视频怎样变成算法可用的图像3.1 RTSP 入口与客户端视频后端连续视频使用 RTSP 地址访问SDK 示例的地址模板为 rtsp://IP:2554/live_camera_id。其中 IP 选择机器人设备camera_id 选择相机2554 是文档和示例给出的默认端口。网络连接和地址准备好后客户端直接打开这条视频流。[2]官方 get_video_stream.py 使用 OpenCV 的 VideoCapture先尝试 FFmpeg 后端失败后再尝试默认后端。后端负责处理视频输入和解码等细节应用通过 open() 打开输入通过 read() 逐帧取得已经解码的图像。OpenCV 对 read() 的定义也明确包含取帧、解码和返回图像这几个动作。[2] [3]因此在这份示例中模型的接入位置十分具体read() 返回有效的 frame 后程序把它交给 _handle_frame()。源码在这一位置留下了视觉算法处理入口。应用可以把图像缩放、通道处理和模型推理接在这里机器人视觉入口与具体识别算法由此通过图像帧衔接起来。[2]3.2 网络媒体流与本地录像的表示不同同一段视频在不同位置有不同的表示。经过网络入口进入客户端的是媒体流VideoCapture 交给 Python 程序的是解码后的图像数组示例随后调用 VideoWriter把这些图像重新编码并写入本地 MP4。图2按数据所处位置展示了这几个阶段。[2] [3] [4]图2 从视频输入到像素帧与本地录像。VideoCapture 完成取流与解码视觉算法消费图像帧VideoWriter 负责本地录像输出。示例中的 mp4v 属于输出端配置。[2–4]这个表示变化会影响对参数的理解。示例中的 mp4v 用于配置 VideoWriter 的输出编码它说明本地文件怎样写入。分析网络传输方式时则应读取视频输入端的实际媒体信息。文件封装格式、输出编码和摄像头输入流的编码需要按各自所在的模块解释。类似地示例日志累加 frame.nbytes。NumPy 将 nbytes 定义为数组元素占用的字节总数所以这里统计的是解码后像素数据的规模适合帮助分析内存读写和处理量网络带宽需要在媒体流或网络层另外统计。把像素字节数除以时间得到的也是对应的像素数据处理量。[2] [5]4 取流与模型推理怎样各自推进官方视频示例采用顺序循环读一帧、处理一帧、写入录像再读下一帧。这个结构便于展示能力接入但把耗时模型直接放进处理函数后后续 read() 也会等待模型返回。随着处理时间增加接收、解码、推理或写盘中的某一环可能成为整条链路的瓶颈。[2]面向需要持续观察现场的应用可以在公开取流入口之上把取流解码与模型推理安排到不同工作单元中。取流模块持续更新可用图像模型准备好处理下一次输入时再取出适合当前任务的帧。图3给出一种应用组织方式预览、推理和录像分别采用符合自身用途的数据消费策略。图3 取流、预览、推理与录像的应用组织示意。最新帧缓存服务于持续画面理解录像使用有界顺序队列这是依据公开读流入口提出的应用设计。对于单帧目标识别、实时预览这类强调及时性的任务可以保留一个容量有限的最新帧缓存。模型处理当前帧时新到的图像更新待处理输入模型空闲后读取较新的帧。这样可以限制应用内部的积压让较慢的模型按自身能力使用视频。需要连续动作片段或严格时序信息的算法则应保留相应时间窗口不能直接沿用只取最新帧的策略。这类取舍发生在已经解码的图像层。输入媒体流的处理仍交给视频后端应用按用途选择哪些像素帧交给后续模块。实现共享缓存时还应保证模型正在读取的图像不会被写入方同时修改可以通过只读引用、受控交接或必要的复制安排数据所有权。录像通常更关注过程的顺序和覆盖范围适合使用独立的有界队列与写入模块。需要保护取流节奏时录像分支可采用非阻塞入队并在队列满时记录丢帧或停止本次录制。若要求完整保留过程就要保证写入吞吐并明确是否允许阻塞上游。预览则倾向于尽快显示当前画面。不同消费者由此获得符合各自用途的缓存与调度策略。集中读取并分发帧的设计也把管理责任集中到了接入模块它负责维护视频连接、解释读帧错误并释放资源。发生断流后如果应用需要重连应由这一模块有节奏地重新建立读取通路同时更新连接代次使消费者能够区分断流前后的图像。官方示例提供了读帧失败后的退出和资源释放持续重连需要应用继续实现。[2]5 怎样读懂帧率和时延视觉应用中出现的多个帧率描述的对象可能不同。视频后端返回的流属性、程序每秒处理的帧数、模型每秒完成的推理数以及录像文件采用的帧率都需要分别记录。表2将这些数值放回相应模块便于理解性能瓶颈发生在哪里。表2 视觉数据链路中的指标应在对应位置解释指标观察位置说明的事情流帧率属性VideoCapture 的 CAP_PROP_FPS后端提供的输入属性需要结合后端支持情况解释应用处理帧率应用收到并处理帧的数量与时间当前读流和处理流程的实际推进速度推理耗时与排队时间帧进入模型前后模型处理速度与应用内部等待录像输出帧率VideoWriter 的 fps 参数写出视频的播放时间基准像素数据量frame.nbytes 及其累计值解码后图像数组的数据规模字段与程序行为依据官方视频示例OpenCV 与 NumPy 文档用于解释属性语义。[2–5]例如示例会读取 CAP_PROP_FPS读取值不可用时采用 25.0 作为本地录像的回退帧率。这个常量属于保存模块的参数选择。要了解程序实际处理速度应结合帧计数与经过的时间要了解模型速度则另外记录每次推理的耗时。OpenCV 也提示读取属性的结果会受到后端和设备实现影响。[2] [3]主动抽帧或丢帧后若仍按原来的固定帧率写出录像中的时长可能随之改变。需要保留真实时间关系时应记录原帧时间并选择适合的输出帧率或支持时间戳的录制方式。[4]时间记录同样要明确起点。示例从第一帧交给应用后开始用 time.monotonic() 统计经过的时间。应用可以在帧进入缓存、开始推理和结束推理时继续记录本地时间由此得到排队与处理耗时。相机曝光到模型输入的完整时延还需要可靠的源端采集时间及相应的时间基准仅有客户端计时只能描述客户端能够观察到的这段过程。[2]为了让识别结果可以回到正确的画面应用还可以在接入时附加帧序号、连接代次和接收时间并让推理结果保留这些信息。界面据此选择对应帧叠加识别结果日志也能定位是哪一张图、在哪一次连接中产生了输出。这些关联属于视觉数据管理可以独立于模型的具体类别和大小实现。6 沿数据通路定位问题与扩展能力有了前面的职责划分排查可以从最近一个正常交接点继续。抓拍服务失败时先查看相机标识、服务响应和等待新帧的状态RTSP 无法打开时先检查地址、网络可达性和视频后端。输入能打开却读不到有效帧时再观察媒体接收与解码情况。这样排查顺序就对应到真实的数据路径。如果画面能够持续读取但推理输入越来越旧应继续比较读帧节奏、缓存长度和模型耗时如果预览正常而录像异常则把注意力放到输出编码、帧尺寸、录像帧率和写盘上。启元 PrimeConsole 提供实时视频监控入口可以辅助观察机器人画面自己的应用仍需要保留上述分层信息才能定位其中的差异。[1]从扩展角度看只接入一次取流并在应用内部共享解码帧可以减少同一进程中重复读取和解码的机会把消费者放到不同进程或设备上则需要继续处理传输、复制和资源分配。两种组织方式各有成本选择应围绕实际的延迟、吞吐与部署需求。回到一开始的拍照、预览和识别需求启元 Q1 的视觉接口提供了不同的数据入口也给出了清楚的算法接入位置。抓拍服务交付一次图像RTSP 支撑连续输入客户端后端把媒体数据变成像素应用再按各模块的需求分配这些帧。读懂这些交接关系开发者就能明确该在哪一层接入模型、保存记录以及处理数据跟不上的问题。参考资料启元接口与示例按 Q1 SDK v1.0.0.0 核对资料查阅日期为 2026 年 10 月 19 日。下列 SDK 资料包包含正文所述消息定义与 Python 示例。[1]启元开发者社区 PrimeConsole 与资料下载Q1 SDK v1.0.0.0 的下载入口以及 PrimeConsole 实时视频监控功能说明。[2]Q1 SDK v1.0.0.0 官方资料包《接口说明》第 2.3.2.1 节视觉采集管理相机请求与消息定义aimdk_msgs/hal/camera/srv/CaptureJpegImage.srvaimdk_msgs/hal/camera/msg/JpegImage.msg示例examples/python/get_jpg.pyexamples/python/get_video_stream.py。[3]OpenCV VideoCapture 类参考用于解释 open、read、视频后端和属性读取的职责。[4]OpenCV VideoWriter 类参考用于解释本地视频输出的编码、帧率与图像尺寸参数。[5]NumPy ndarray.nbytes 字段说明用于解释示例中解码后图像数组的元素字节数。启元机器人开发者社区想进一步查看启元 Q1 的开发文档、SDK 与视觉应用实践可以访问启元机器人开发者社区结合相关开放资料继续探索机器人的视觉感知与应用开发。hello这里是 晓雨的笔记本。如果你喜欢我的文章欢迎点赞、关注和评论我会持续分享具身智能与机器人开发的技术实践。欢迎大家添加好友交流。