本文档以airbot_ie默认配置为例介绍了一些常见的配置调整说明，帮助用户更好地理解和使用数据采集系统（无特殊说明，文件路径均相对于airbot_ie目录）。
update_rate: 数据采集频率。数据采集时按此频率将全部组件的观测数据添加到采样器中sample_limit.start_round: 数据采集的起始轮数。如果已经采集有数据，请对应修改，避免覆盖已有数据。默认设置为-1，自动根据保存目录下已采集的数据文件数量自动确定起始轮数（不会自动判断文件序号，因此如果文件编号不连续，会导致起始轮数判断错误）。sample_limit.size: 采样帧数的上限。一方面，有些算法程序要求采集的数据帧数一致，另一方面，可以避免忘记停止采集而导致采集数据量过大内存溢出。默认设置为1000sample_every: 降采样频率（仅在 sampling 状态生效）。设为N时每N个 tick 保存一帧数据（默认1= 每帧都保存）。用于减少存储/编码开销，同时保持仿真全分辨率运行（轨迹保真）。与 runner 端的demo_stride正交（后者减少回放动作数）。sample_limit.size阈值检查已保存帧数，而非总 tick 数。manager_update_every: 按 manager 分别设置更新分频（字典，键为 manager 名）。设为{manager_name: N}时该 manager 每N个主循环 tick 更新一次；未设置的 manager 每 tick 都更新。用于解耦不同模块的更新频率，例如{self_manager: 3}可让仿真 (auto_atom) 每 tick 运行，但采样/保存每 3 tick 一次。注意：分频计数器是全局的（跨 episode），不在每轮开始时重置，因此某些 episode 的首帧可能被跳过。如需确保每轮首帧都采集，用sample_every（episode-local 计数器）或在 runner 端降采样 (demo_stride)。
支持配置在数据采集状态变化时自动执行指定动作，例如在每次开始采集前自动将机器人重置到初始位姿等，可参考configs/demonstrators/test.yaml中的send_actions字段进行配置（注意不要直接在test.yaml中修改）。
首次配置失败（例如相机未找到、CAN 未连接、相机端口变化等）时的行为由 self manager 的 exit_on_configure_failure 字段控制（默认 true）：
true（默认）：配置失败后自动触发finish结束并退出程序。false：停留在unconfigured状态，不退出。此时可在修复设备 / 配置后按c键重试配置（configure动作），或按Ctrl+C退出。
命令行覆盖示例（键盘管理器下 self manager 位于 managers.self_manager）：
airdc managers.self_manager.exit_on_configure_failure=false默认情况下深度相机不采集深度数据（体积较大），如果需要采集，可参考configs/demonstrators/realsense.yaml中的参数，在相应相机配置字段下添加enable_depth和align_depth字段并设置为true。点云数据不支持也不建议直接采集，请自行结合相机参数信息从深度图像中生成。
相机支持 enable_color、enable_depth、enable_mask、enable_heat_map 等字段控制采集哪些图像模态（要求 enable_color、enable_depth 至少一个为 true）。除了在单个相机配置下写死，也可以在配置顶层定义这些键，并在各相机配置下用插值引用（如 enable_depth: ${enable_depth}），从而用一个顶层开关统一控制所有相机。AAO 仿真采集即采用该方式，详见 AAO 仿真数据采集 的「采集模态」一节。
相机支持非阻塞取图模式，可在相机配置中增加blocking字段并设置为false，这样可以避免因相机帧率不足影响整体数据采集频率，不过会导致相机数据中出现重复帧（目前暂不支持相机端异步不等长采集，但可通过配置视频编码器端的采集策略实现最终不等长的数据存储，见视频编码参数）。
RealSense相机的分辨率和帧率等配置受USB口是否为USB3.0影响，可通过安装使用rs-enumerate-devices命令查看相机支持的分辨率和帧率，并在配置文件中进行相应修改。
可在对应相机的配置下，增加如下参数以覆盖默认相机信息：
rgb_camera:
intrinsics:
distortion_model: plumb_bob
d: [0.0, 0.0, 0.0, 0.0, 0.0]
k: [615.0, 0.0, 320.0, 0.0, 615.0, 240.0, 0.0, 0.0, 1.0]
binning_x: 0
binning_y: 0
calibration:
r: [1.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 1.0]
p: [615.0, 0.0, 320.0, 0.0, 0.0, 615.0, 240.0, 0.0, 0.0, 0.0, 1.0, 0.0]
roi:
x_offset: 0
y_offset: 0
height: 0
width: 0
do_rectify: false深度模组的配置类似，只是字段名称替换为depth_module即可。
内置的GroupedDemonstrator示教器通常可满足大部分数据采集需求，常见配置如下：
默认情况下，需要根据机器人实际使用方式手动启动遥操作控制。若要开启自动遥操作控制，需调整demonstrator.auto_control下的如下字段：
groups字段设置为null（注意不是列表[null]）；- 增加
modes字段并设置为列表[process]（process表示以子进程的方式启动控制程序）； - 增加
rates字段并设置为列表[100]（100是默认的遥操控制频率，理论上数据采集的更新频率不应超过该值）。 前提是要保证follower的send_action方法能正确处理leader的capture_observation方法的返回值。
支持对采集到的leader观测数据进行后处理配置，例如对关节位置数据进行范围限制，或对位姿数据进行坐标变换等。可通过在demonstrator.post_capture字段下增加对应的配置实现，具体可参考configs/demonstrators/post_capture目录下的配置示例。将整个字段设置为null表示对所有leader组件启用内置的默认自动后处理。同理，将某个组的leader名称对应的值设置为null表示对该组启用默认后处理。此外，transform参数也支持设置为null，表示使用内置的默认坐标变换处理。注意，目前通常手动覆盖部分配置会导致全部默认配置失效，因此对于存在默认配置的情况应小心修改，避免遗漏必要的配置项。
默认情况下，各个组件的观测是依次按顺序被获取的。在阻塞模式下，如果某些组件的调用时间较长，可能会影响整体的数据采集频率；尽管非阻塞模式下可以避免该问题，但是失去了数据获取的同步性，并且多个组件在同一进程中也会互相竞争资源降低整体性能。为避免上述问题，可以将组件类通过airdc.common.systems.wrappers.concurrent_instantiate函数进行并发包裹和实例化，将原类型的观测获取转换为基于共享内存的多进程调用，从而提升整体性能。目前已测试了各种相机的并发获取（图像类型为NDArray），具体可参考configs/demonstrators/concurrent.yaml中的配置示例。注意，并发调用需要额外的系统资源开销，请仅对真正有需要的组件使用。
- 数据过滤：支持通过
key_filtering字段配置可视化器的数据过滤规则，以筛选出支持可视化的数据进行显示，省去额外的无效数据处理代码逻辑。参考airbot_ie/configs/basis.yaml中的配置示例。 - 交换颜色通道：支持通过
swap_rgb_bgr字段支持RGB和BGR颜色通道的互转，以适配不同的相机和显示设备。 - 编码格式：支持通过
pixel_format字段指定图像数据的编码格式，如MJPEG、YUYV等，以适配不同的相机输出格式的解码。
支持可视化NDArray和bytes类型的图像。NDArray类型支持shape为(H, W, 3)的彩色图像和(H, W)的灰度、深度图像，以及(H, W, C)任意通道维度（C不等于3）的图像（例如heatmap图像）。
如果需要在headless模式下运行，即不显示GUI窗口，可在配置文件中去除visualizers字段，或将visualizers.names设置为空列表[]。
除了默认采样器，还支持：
- 类：
airdc.common.samplers.mcap_sampler_ros.McapDataSamplerROS。 - 后端：该采样器会根据
ROS_VERSION环境变量选择相应版本的后端。各后端说明如下：- ROS1：尽管ROS1本身不支持MCAP格式，但是其保存的MCAP文件可以支持
Foxglove可视化以及通过mcap-ros1-support包读取。使用虚拟环境时，通常需额外安装以下依赖：pip install rospkg catkin_pkg empy。 - ROS2：其保存的MCAP的消息格式与录制的Bag文件兼容。但需注意虚拟环境的Python版本需与ROS2版本对应的Python版本匹配。
- ROS1：尽管ROS1本身不支持MCAP格式，但是其保存的MCAP文件可以支持
- 示例配置:
airbot_ie/configs/samplers/ros.yaml
- 类：
airdc.common.samplers.mcap_samplers.sampler_ros_struct.McapDataSamplerROSStruct。 - 示例配置：
airbot_ie/configs/samplers/ros_struct.yaml。 - 适用场景：采集数据已经按ROS消息结构组织完成，输入数据的key即为最终写入MCAP的ROS topic，
data字段为对应ROS消息的完整字典或可转换数组。 - 与
MCAP-ROS采样器的区别：该采样器不按topic/field拆分字段再拼接ROS消息，也不走FlatBuffers fallback；每个输入key会直接写成一个ROS消息topic。无法从topic名称推断ROS消息类型时，会按std_msgs/Float32MultiArray写入。 - 常用自动类型映射：key末尾为
video_encoded时按foxglove_msgs/CompressedVideo写入；image_raw和heat_map按sensor_msgs/Image写入；rotation_angle按geometry_msgs/Vector3Stamped写入；points按sensor_msgs/PointCloud2写入。其他topic通常需要末尾名称能映射到ROS消息名，例如camera_info、pose、joint_state、transform。
不同任务一般需要手动配置一些基本信息，可通过sampler.task_info字段配置，这些信息将可能在后续用作区分不同类型数据，以及可能用作模型的prompt。示例配置可参考airbot_ie/configs/task_info/pick_and_place_blocks.yaml。可通过+task_info=pick_and_place_blocks命令行参数灵活指定任务信息配置。
为基于McapFlbDataSampler的sampler增加配置：video_save_to: folder，这样视频数据将不保存到mcap文件中，而是独立保存为.mp4文件到文件夹中。MCAP-ROS-Struct采样器不支持该字段，其video_encoded数据会写入MCAP中的ROS CompressedVideo topic。
为sampler增加配置av_coder，常用字段如下：
non_monotonic_mode用于设置非单调递增的视频帧的处理方式，可选值如下：adjust：调整时间戳以保证单调递增（增加一个微小量）。默认值。drop：丢弃。适用于对视频数据的异步非等长采集场景。raise：抛出异常none：不做处理，可能导致一些视频编解码问题。
non_monotonic_log用于控制是否打印非单调递增的日志信息，默认值为true。
默认情况下各个组件的数据拥有自己独立的键名，例如arm和eef分别拥有自己的joint_state数据。ROS通常会将这些数据合并到同一个joint_sates话题下发布，因此在采集时需要将这些数据合并。这可以通过在根配置下增加key_merge字段，可配置自定义的函数（输入为原始字典，输出为合并后的字典）或分别指定合并方式函数method和合并指示函数pred，经由内置合并器根据该配置进行合并（适用于大多数情况）。具体可参考：configs/demonstrators/ros.yaml。
默认的grouped demonstrator示教器通过group name、component name和data key三层名称通过/连接形成最终的数据名称，其中data key一般遵循：<sub component name>/<data type>/<field name[optional]>结构。例如/left/leader/arm/joint_state。但ROS通常期望数据名称为：/robot/arm_left_leader/joint_states。为此，可通过在sampler.instance字段下增加key_remap配置，指定一个映射函数，具体可参考：configs/key_remap/example.yaml。
机器人通常可以获取多种数据，例如各种传感器实时数据，以及机器人关节名称信息等。通常，非实时的数据默认通过info接口获取而不被加入观测数据中，但ROS有时会要求将这些数据实时发布以保持完整性，例如JointState消息中包含固定的关节名称信息。为此，可通过在机器人配置文件中的观测接口中增加对应数据类型的接口，具体可参考：configs/robots/airbot_play_with_name.yaml。
当实际采集频率低于设定值时，程序默认会以警告级别打印超时提示，可以通过命令行或者配置文件中设置log_jitter为false来关闭该提示，保持终端整洁。
所有配置均可通过命令行参数进行覆写，默认基于Hydra框架，有如下规则：
- 使用
.分隔层级关系，例如dataset.directory表示配置文件中dataset字段下的directory字段； - 布尔类型使用
true或false表示（首字母小写）； - 不同参数之间使用空格隔开；
- 列表类型使用
"[]"括起，注意使用双引号包裹以避免shell解释错误；元素之间使用英文逗号分隔。 - 通过
airdc -h查看可覆盖命令行参数及其当前值。