11. 数据采集#

11.1 环境配置#

11.1.1 AIRBOT Play SDK#

该部分与AIRBOT Play官方手册中的操作一致，若尚未完成，可参考下方链接点亮，但需关注如下版本要求：

Python : >= 3.10
AIRBOT Play Python SDK : >= 5.1.4
AIRBOT Play Pro Python SDK : >= 5.1.4

推荐创建统一的conda环境进行后续安装：

conda create -n airbot_data python=3.10 && conda activate airbot_data

点击这里查看如何安装 AIRBOT Play 驱动程序和 Python SDK

11.1.2 数据采集工具包#

软件包请进入联络技术支持团队获取。解压后，您将看到以下软件包：

数据采集工程文件夹：（airbot-data-collection）
数据可视化软件包文件夹：（data_viewer）

环境要求

请使用上述安装好AIRBOT相关SDK的Python环境进行后续依赖安装！

conda activate airbot_data
cd airbot-data-collection
bash install.sh

安装结束后终端可能有红色报错提示部分依赖问题，一般可忽略，进行后续操作即可。

11.1.3 机械臂绑定#

为了避免混淆示教臂和执行臂，需要按设备依次绑定 CAN 名称。首先将全部机械臂的数据线从电脑上拔除，然后按如下顺序连接，分两种情况：

单臂控制单臂：示教臂、执行臂
双臂控制双臂：左侧示教臂、左侧执行臂、右侧示教臂、右侧执行臂的顺序依次连接

自动绑定

下述绑定操作目前已在自动配置部分默认自动进行，因此可跳过。但注意，上述按顺序连接设备的操作依然需要严格执行，否则会造成设备对应错误。

连接好后，可执行如下命令进行绑定，同样分两种情况：

单臂控制单臂

sudo ./tools/bind_can_udev.sh --target can_lead can_follow

双臂控制双臂

sudo ./tools/bind_can_udev.sh --target can_left_lead can_left can_right_lead can_right

命令执行结束后，再次将全部机械臂的数据线从电脑上拔除，然后重新连接，顺序无要求。连接好后，执行如下命令检查是否成功绑定：

ip l |grep can_

如果输出中包含绑定命令中--target后指定的全部名称，则绑定成功，例如双臂控双臂情况下应能看到： can_left_lead, can_left, can_right_lead, can_right。

11.1.4 相机检查#

连接所需的全部相机，对于USB相机，可以执行如下命令进行检查：

python3 test/multi_capture.py 2 4 6 -ff MJPEG MJPEG MJPEG

其中2 4 6指定了相机的ID号，可通过ls /dev/video*命令查看并做相应修改，一般来说使用偶数的ID，奇数的ID不可用。 -ff后面的参数指定了每个相机的视频流格式，一般使用MJPEG。

显示异常

如果出现某个相机显示的图像是纯黑，且帧率异常，一个可能的原因是因为错误地启用了电脑自身的摄像头，并且电脑有硬件相机屏蔽的开关（通常在电脑右侧边），此时可将尝试其他的相机ID，包括尝试ID为0的情况，因为有些设备的电脑内置摄像头ID未必为0。
如果出现无法同时开启多个相机，请尝试将相机尽可能分散到电脑的不同USB口中（充分利用Type-C口），尽量不要再一个拓展坞上连接多个相机。如果仍然无法同时开启，考虑使用如下命令临时修改uvc内核模块配置： sudo rmmod uvcvideo && sudo modprobe uvcvideo nodrop=1 timeout=5000 quirks=0x80，然后重新尝试。如果上述修改后仍然无效，可以考虑调整每个相机的视频流格式，默认为MJPEG，可尝试将不同相机改为YUYV，特别是不同型号的相机混用的情况下，可能型号1的相机设置为MJPEG，型号2的相机设置为YUYV的情况下才能同时使用。如果上述修改有效，最后可以考虑执行如下命令永久调整uvc内核配置：echo "options uvcvideo nodrop=1 timeout=5000 quirks=0x80" | sudo tee -a /etc/modprobe.d/uvcvideo.conf >/dev/null
RealSense相机也会占用/dev/video号，因此当与USB相机一起连接到电脑上时需要注意区分

对于Intel-RealSense相机，可以执行如下命令查看已连接相机的序列号：

依赖安装

Python < 3.12: pip install pyrealsense2
Python >= 3.12: pip install pyrealsense2-beta

python3 common/robot_devices/cameras/intelrealsense.py

11.1.5 自动配置#

绑定事项

如果尚未绑定机械臂，执行下述命令后会默认自动进行绑定，请根据终端提示拔掉设备并重新连接即可
同时使用多个USB相机时往往会因为相机连接顺序变化而导致设备号变化，造成数据记录的语义与实际不符，例如名为env_camera的环境相机实际上可能错误地对应了臂载相机。为了解决这个问题，自动配置程序使用了USB端口号代替设备号进行配置。

运行如下程序进行自动绑定：

python3 tools/setup.py -ic 0

其中-ic通常用于忽略0号笔记本电脑内置相机，如果有其他需要忽略的相机，可以继续添加 ID，ID 用空格隔开。如果不需要忽略相机，请修改为-1或去掉该参数。部分设备可能由于上电开机前同时连接多个设备造成内置相机设备号不为0，请根据实际情况修改。

启动后，该程序会要求输入密码，这是为了获取设备的序列号便于匹配不同设备。而后会自动检测设备所连接的所有相机并通过图形窗口实时显示图像，图像上方标题的格式为：名称-ID-USB端口信息或序列号，如果未曾配置过或者相机连接端口号发生变更，则名称为None，此时可按c键进行配置，此时终端会提示要对某个端口号的相机命名，通过数字按键选择对应名称（规范化的可选名称在tools/station_config.yaml中配置，通常不需修改），如果只剩一个相机和一个可选名称未被配置则会自动完成。配置完成后建议通过图像窗口检查名称是否符合实际，然后按s键保存配置并退出，配置文件将保存到defaults/config_setup.yaml中。可以根据使用情况手动修改该配置文件，例如机械臂的端口号、数据保存目录等。

手动修改配置

配置文件的生成基于defaults/config_full.yaml，主要是覆写了components配置以及增加了post_capture配置（默认值位于defaults/post_capture，主要用于将示教器的控制范围映射到执行器的范围内），因此为防止重新生成配置后覆盖，建议不要直接修改config_setup.yaml，而是修改上述默认配置文件。
不同任务一般需要手动对配置文件中的参数进行修改，特别是task_info中的任务名称等，这些信息将可能在后续用作区分不同类型数据，以及可能用作模型的prompt。

11.2 启动 AIRBOT Play#

初次使用请参考初次点亮 AIRBOT Play 熟悉机械臂的基本使用。

数据采集每组至少需要用到两台机械臂，一台作为示教臂（可以是安装有末端示教器的 AIRBOT Play 或 AIRBOT Replay），另一台作为执行臂（末端安装有二指夹爪）。

依次启动两台机械臂，注意根据实际情况修改 CAN 号接口和端口号：

在终端 1 中执行如下命令启动示教臂：

2 控 2 绑定情况：

airbot_server -i can_left_lead -p 50050

1 控 1 绑定情况：
```
airbot_server -i can_lead -p 50050
```
在终端 2 中执行如下命令启动执行臂：
2 控 2 绑定情况：
```
airbot_server -i can_left -p 50051
```
1 控 1 绑定情况：
```
airbot_server -i can_follow -p 50051
```
同理，如果是两组遥操作（2 控 2 绑定），继续启动剩下的两条臂：

airbot_server -i can_right_lead -p 50052
airbot_server -i can_right -p 50053

11.3 数据采集流程#

11.3.1 运行数据采集程序#

简化命令

如果完成了自动配置，则上述命令通常可以进行简化，见简化命令。

下面对几种常用的控制情况分别给出示例命令：

一条示教臂控制一条执行臂，且使用 1 个 USB 相机：

python3 main.py --path defaults/config.yaml \
                --components.names lead follow "" \
                --components.paths airbot_play airbot_play v4l2 \
                --components.params '{}' '{"port": 50051}' '{"camera_index": 0, "pixel_format": "MJPEG"}' \
                --components.roles l f o \
                --components.groups "/" "/" "/" \
                --dataset.directory example \
                --auto-control.rate 100 \
                --update-rate 20 \
                --sample-limit.start-round -1 \
                --sample-limit.size 1000

两条示教臂控制两条执行臂，且使用 3 个 USB 相机为例：

python3 main.py --path defaults/config.yaml \
                --components.names lead follow "" lead follow "" "" \
                --components.paths airbot_play airbot_play v4l2 airbot_play airbot_play v4l2 v4l2 \
                --components.params '{}' '{"port": 50051}' '{"camera_index": 0}' '{"port": 50052}' '{"port": 50053}' '{"camera_index": 2}' '{"camera_index": 4}' \
                --components.roles l f o l f o o \
                --components.groups left left left_camera right right right_camera env_camera \
                --dataset.directory example \
                --auto-control.rate 100 \
                --update-rate 20 \
                --sample-limit.start-round -1 \
                --sample-limit.size 1000

参数解释如下：

--path: 配置文件路径，存放了默认参数，这些参数的优先级较低，会被命令行中指定的参数进行覆盖。
--components.names: 组件的名称，每个组件可以是示教臂、执行臂以及相机等，会作为保存的数据字典中的Key的一部分
--components.paths: 组件的配置文件路径或名称。如果是名称，需要将配置文件放于main.py目录或其子目录内，例如v4l2位于airbot/configs/sensors/cameras/v4l2.yaml。配置文件内容符合Hydra格式，其中包括有组件的类路径，以及默认参数，一般不需额外修改
--components.params: 组件的参数，用于覆盖配置文件中的默认参数，比如不同的机械臂使用不同的端口号参数，不同的相机使用不同的 ID 号和视频格式
--components.roles: 组件的角色，包括l（leader）/f（follower）/o（other/observer，如相机）三种，需结合组件的实际情况修改
--components.groups: 组件所在组，每个组可以有 0 个或 1 个 l，若存在 l 则至少要有一个 f，否则不应有任何 f，o 的数量不限。组的名称会做为保存的数据字典的前缀，若为/则会被省略
--dataset.directory: 数据保存的目录，一般以任务名命名
--auto-control.rate: 自动控制频率。数据采集时按此频率循环获取 leader 的观测，作为控制量发送给 follower
--update-rate: 数据采集频率。数据采集时按此频率将全部组件的观测数据添加到采样器中
--sample-limit.start-round: 数据采集的起始轮数。如果已经采集有数据，请对应修改，避免覆盖已有数据，或者设置为-1，则将根据保存目录下已采集的数据文件数量自动确定起始轮数
--sample-limit.size: 采样帧数的上限。一方面，有些算法程序要求采集的数据帧数一致，另一方面，可以避免忘记停止采集而导致采集数据量过大内存溢出

如果需要在headless模式下运行，即不显示 GUI 窗口，可在命令最后增加--visualizers.names参数。如果不需要开启自动控制，可在命令最后增加--auto-control.groups参数。

常见问题处理

错误一般由命令行参数配置修改不当引起。所以请仔细检查配置是否与实际设备的连接情况一致。
如果报错信息中出现opencv字样，首先检查卸载opencv-headless后重装opencv-python的操作有没有正常进行，检查对应相机的帧率是否正确匹配对应相机，并将连接到电脑的相机数据线重新拔掉后查看电脑内置相机的camera_index，最后按顺序连接相机。
机械臂测试程序和数据采集程序启动后都会全局读取键盘上的所有按键输入，如果需要其它操作例如打字搜索请先关闭程序，否则容易发生异常。
由于defaults/config.yaml中没有配置post_capture，因此可能会出现示教时夹爪无法张开到最大的情况，此时要么使用自动配置生成配置文件，要么手动修改config.yaml文件

RealSense 相机支持

如果需要使用RealSense相机，只需要将--components.paths参数中的v4l2改成 realsense，同时将--components.params中的相机序号修改为 RealSense相机的序列号。如果只有一个相机，可以设置为 None，例如'{"camera_index": None}'，此时程序将自动获取该设备的序列号。

然后可以使用键盘进行数据采集的流程控制，键盘使用说明在可在终端打印中上滚看到，或者按键盘i键重新打印。

11.3.2 简化命令#

如果完成了自动配置，则上述命令通常可以进行简化，主要是去掉了各组件的配置：

python3 main.py --path defaults/config_setup.yaml --dataset.directory example

如果需要调整其他配置，可以继续增加其他命令行参数即可。

11.3.3 数据采集建议#

为了保证数据采集的质量，有如下建议：

机械臂控制

运动过程平稳流畅自然，没有明显加速、停顿、抖动等速度突变情况；
数据采集轨迹分布应具有一定的随机性，但请注意动作分布差异不要过大；
夹爪开合的动作应比较明显，即张开时尽量张开，关闭时尽量关闭，保证主动臂和从动臂编码器返回明确的开合值；
每个动作之间有一定停顿；
在操作物体时应考虑模型预测可能出现的偏差，不要出现仅夹住物体边缘的情况；

相机

采集图像清晰，相机对焦点正常，画面无卡顿、模糊、抽帧等问题；
环境相机中保证操作物体全程位于画面中（杯子等较大物体允许有几帧不整体入镜）；
环境相机注意操作角度，避免位于夹爪遮挡小物体的角度，如下图所示；
臂上相机应保证可以看到操作物体和夹爪的开合特征；
环境相机视野中，示教臂不可入镜（因推理时不存在），执行臂在任务开始时可不必须入镜，但在操作物体时要求可以看到夹爪与物体的交互；
相机视野应考虑改变物体摆放位置后，物体仍位于相机视野中，且物体的初始摆放位置应尽量位于相机视野中央；

11.3.4 数据采集操作#

按空格键开始数据采集
完成任务后按s键保存, 等待保存完毕后, 再次按下空格键开始采集
若在采集过程中, 发现本次操作有不符合采集要求时，主观认为是无效数据，则按q键放弃当前采集，然后重新按空格键开始采集
若数据已经保存，发现采集的数据不符合要求，则可按r键删除本次采集的数据，然后按空格键重新采集
所有数据采集完毕后, 按z键或ESC键退出采集程序

11.4 数据可视化#

打开data_viewer文件夹，双击其中的index.html文件在浏览器中打开：

然后点击左上角的蓝色浏览图标：

在新出现的小窗体中选中需要查看的 bson 格式的数据文件

然后点击左侧的+号选择要可视化的数据类型（图表或视频）

选择后右侧会增加一栏窗口，右键该窗口：

选择蓝色的设置按钮，然后可以在 Topic 栏中筛选要显示的数据名称：

alt text

选择完毕后点击下图上方右侧的三角形播放按钮对数据进行动态可视化：

可视化效果如下图所示：

alt text