本文档整理了当前项目中涉及的相机配置说明、视频异常现象分析、三目画面显示方法，以及 ROS2 常用命令速查，便于调试和日常使用。

1. 配置文件说明

当前配置文件为 config/fays_vikit.yaml。

1.1 Middle RGB Camera

这一部分配置中间 RGB 彩色相机。

rgb_dev_port: /dev/video4

  • 中间 RGB 相机对应的 Linux 设备节点。

  • 驱动启动时会尝试打开 /dev/video4。

awb: true

  • 自动白平衡开关。

  • true 表示开启自动白平衡。

rgb_white_balance_r: 1.3

rgb_white_balance_g: 0.8

rgb_white_balance_b: 2.1

  • RGB 三个通道的白平衡系数。

  • 在关闭自动白平衡时，这几个值通常更有意义。

  • 用于修正画面偏色问题。

rgb_rotate: 0

  • 中间 RGB 图像旋转角度。

  • 当前仅支持 0 或 180。

  • 0 为不旋转180 为倒转。

mid_img_fmt: 1

  • 中间相机输出格式。

  • 0 表示 Bayer 原始图像。

  • 1 表示 RGB 彩色图像。

rgb_cam_width: 1920

rgb_cam_height: 1080

  • 中间 RGB 相机输出分辨率。

  • 当前配置为 1920x1080。

1.2 Stereo Camera

这一部分配置双目相机。

stereo_dev_port: /dev/video6

  • 双目相机设备节点。

stereo_single_cam_width: 1280

stereo_single_cam_height: 800

  • 单个相机的图像宽高。

  • 即左目一张图 1280x800，右目一张图也是 1280x800。

stereo_fps: 25

  • 双目相机帧率。

  • 常见可选值为 25 或 50。

stereo_color_mode: 1

  • 双目彩色相机输出模式。

  • 0 为 raw 原始图像。

  • 1 为 RGB 图像。

stereo_awb: 1

  • 双目 RGB 自动白平衡开关。

  • 一般 1 表示开启0 表示关闭。

stereo_R_gain: 1.0

stereo_G_gain: 0.6

stereo_B_gain: 1.3

  • 双目 RGB 传感器的数字增益。

  • 通常在关闭自动白平衡时更有参考意义。

stereo_init_exposure: -1

  • 双目初始曝光设置。

  • -1 表示先自动曝光初始化，再固定。

  • 1.0 ~ 885.0 表示手动曝光值。

stereo_gain_value: -1

  • 双目相机增益控制。

  • -1 表示自动增益。

  • 1.0 ~ 15.0 表示手动增益。

left_cam_rotate_180: 0

  • 左目图像是否旋转 180 度。

  • 0 不旋转1 旋转。

right_cam_rotate_180: 1

  • 右目图像是否旋转 180 度。

stereo_swap_lr: 0

  • 是否交换左右图像。

  • 0 不交换1 交换。

1.3 IMU

这一部分配置惯性测量单元。

imu_dev_port: /dev/video8

  • IMU 对应的设备节点。

gravity: 9.7946

  • 当前地区使用的重力加速度值，单位通常为 m/s^2。

  • 用于 IMU 标定和姿态估计。

1.4 当前配置的整体含义

当前配置可以理解为：

  • 中间 RGB 相机使用 /dev/video4

  • 输出 1920x1080 的 RGB 图像

  • 自动白平衡开启

  • 图像不旋转

  • 双目相机使用 /dev/video6

  • 每个相机输出 1280x800

  • 帧率为 25

  • 双目输出 RGB 图像

  • 双目自动白平衡开启

  • 曝光和增益使用自动模式

  • 左目不旋转，右目旋转 180 度

  • IMU 使用 /dev/video8

  • 重力常数设置为 9.7946

2. 视频画面异常分析

从 RViz 截图观察，异常通常表现为以下几类：

  • 画面整体过曝，亮部发白

  • 颜色明显偏绿或偏青

  • 图像方向不符合预期

2.1 可能原因

白平衡异常

中间 RGB 当前参数：


awb: true

rgb_white_balance_r: 1.3

rgb_white_balance_g: 0.8

rgb_white_balance_b: 2.1

可能的问题：

  • 自动白平衡没有稳定下来

  • 驱动在自动白平衡开启时仍参考手动增益

  • 环境光源复杂，导致 AWB 判断失准

曝光和增益偏高

双目当前参数：


stereo_init_exposure: -1

stereo_gain_value: -1

这表示自动曝光和自动增益参与控制，强光环境下容易过曝。

图像方向不对

如果相机是倒装的，而 rgb_rotate: 0，画面就会方向异常。

2.2 推荐排查顺序

建议不要一次改很多参数，而是按顺序测试。

第一步：先处理中间 RGB 偏色

先尝试关闭自动白平衡，并把手动白平衡恢复到中性值：


awb: false

rgb_white_balance_r: 1.0

rgb_white_balance_g: 1.0

rgb_white_balance_b: 1.0

如果画面明显正常很多，说明问题主要来自白平衡。

然后可以小幅微调，例如：


rgb_white_balance_r: 1.1

rgb_white_balance_g: 1.0

rgb_white_balance_b: 1.1

第二步：如果图像方向不对，修改旋转


rgb_rotate: 180

这只解决上下翻转，不解决物理斜装。

第三步：如果显示的是双目图像，再调双目参数

保守调试版本可先设为：


stereo_awb: 0

stereo_R_gain: 1.0

stereo_G_gain: 1.0

stereo_B_gain: 1.0

stereo_init_exposure: 80

stereo_gain_value: 1.0

适用于室内固定光照环境。

2.3 建议优先试的最小改动

优先只改这几行：


awb: false

rgb_white_balance_r: 1.0

rgb_white_balance_g: 1.0

rgb_white_balance_b: 1.0

如果方向不对，再加：


rgb_rotate: 180

3. 为什么重新执行 FTDI 权限脚本会恢复正常

相关脚本的作用通常包括：

  • 检测 FTDI Superspeed Video Bridge 设备

  • 生成 udev 规则

  • 重新加载规则

  • 触发设备重新匹配

  • 把用户加入 video 和 plugdev 组

3.1 重新执行脚本后恢复的常见原因

规则第一次没有及时生效

可能流程是：

  1. 设备先插入并创建设备节点

  2. 此时规则还没写入或未 reload

  3. 节点权限不对

  4. 重新执行脚本后udevadm trigger 让规则真正生效

用户组修改不会立刻影响当前终端

脚本中的：


sudo usermod -a -G video,plugdev $USER

不会立刻让当前 shell 拥有新组权限，通常需要重新登录或打开新的会话。

设备节点顺序发生变化

当前配置写死了：


rgb_dev_port: /dev/video4

stereo_dev_port: /dev/video6

imu_dev_port: /dev/video8

而 /dev/video4/dev/video6/dev/video8 并不一定稳定。重载或重触发后，设备枚举顺序可能变化，从而导致这次“碰巧”又对应上了。

3.2 根本结论

重新执行脚本后恢复正常，通常说明问题更可能出在：

  • 设备权限

  • udev 规则生效时机

  • /dev/video* 设备映射顺序

而不是成像参数本身。

3.3 工程建议

更稳定的做法是避免直接使用 /dev/video4 这类不稳定路径，而改用：

  • /dev/v4l/by-id/...

  • 或自定义 udev 规则生成固定别名，例如 /dev/fays_rgb/dev/fays_stereo/dev/fays_imu

4. RViz 日志中 Stereo is NOT SUPPORTED 的含义

RViz 输出：


[INFO] [xxx] [rviz2]: Stereo is NOT SUPPORTED

[INFO] [xxx] [rviz2]: OpenGl version: 4.6 (GLSL 4.6)

这里的 Stereo 指的是 OpenGL 立体显示能力，不是双目相机。

这条信息说明：

  • 当前图形环境不支持 OpenGL 立体显示

  • 不代表双目相机不可用

  • 不会影响普通图像 topic 的显示

因此，这不是视频异常的根因。

5. 如何显示三目相机画面

在 RViz 中显示三目画面，核心不是直接读取 /dev/video*，而是订阅 ROS 图像 topic。

流程为：

  1. 驱动读取 /dev/video*

  2. 驱动发布 ROS topic

  3. RViz 订阅 topic

  4. Image 组件显示画面

5.1 当前项目里实际发布了哪些 topic

根据当前 ros2 topic list，相关话题为：


/fays/atrak/cam_rgb

/fays/atrak/cam_stereo

/fays/atrak/imu

这意味着当前系统并没有发布三个独立的图像话题，而是：

  • /fays/atrak/cam_rgb：中间 RGB 图像

  • /fays/atrak/cam_stereo：双目合成图像或双目统一输出

5.2 当前能直接显示的画面

当前最直接能显示的是两路：

  1. /fays/atrak/cam_rgb

  2. /fays/atrak/cam_stereo

在 RViz 中操作：

  1. 点击 Add

  2. 添加两个 Image

  3. 分别订阅 /fays/atrak/cam_rgb 和 /fays/atrak/cam_stereo

5.3 为什么不能直接显示三路独立画面

因为目前没有以下这类独立话题：

  • 左目 topic

  • 右目 topic

  • 中间 RGB topic 之外的更多独立流

双目更可能被驱动拼接成一张图，然后统一发布到 /fays/atrak/cam_stereo。

5.4 如果想显示真正的三路独立画面

有两种方法：

方法 1：修改驱动，直接发布三路 topic

例如：

  • /fays/atrak/cam_rgb

  • /fays/atrak/cam_stereo_left

  • /fays/atrak/cam_stereo_right

方法 2：写一个拆分节点

如果 /fays/atrak/cam_stereo 是左右拼接图，可以写一个 ROS2 节点：

  • 订阅 /fays/atrak/cam_stereo

  • 按宽度一分为二

  • 发布 /fays/atrak/cam_left 和 /fays/atrak/cam_right

再加上原有的 /fays/atrak/cam_rgb，就能得到三路独立画面。

5.5 建议先确认 topic 类型


ros2 topic info /fays/atrak/cam_rgb

ros2 topic info /fays/atrak/cam_stereo

如果两者都是 sensor_msgs/msg/Image，那 /fays/atrak/cam_stereo 很可能就是可拆分的图像流。

6. ROS2 常用命令速查

6.1 环境相关


source /opt/ros/<发行版>/setup.bash

source install/setup.bash

echo $ROS_DISTRO

printenv | grep ROS

命令执行效果说明：

  • source /opt/ros/<发行版>/setup.bash

    加载系统安装的 ROS2 环境变量，使 ros2 命令、系统包路径、消息接口路径等生效。

  • source install/setup.bash

    加载当前工作空间的编译结果，使你自己编译的包、节点、launch 文件、接口定义可被 ROS2 识别。

  • echo $ROS_DISTRO

    输出当前终端使用的 ROS2 发行版，例如 humblejazzy。

  • printenv | grep ROS

    列出当前 shell 中所有和 ROS 相关的环境变量，便于排查环境没加载、加载错版本、路径冲突等问题。

6.2 包相关


ros2 pkg list

ros2 pkg prefix <包名>

ros2 pkg prefix --share <包名>

ros2 pkg executables <包名>

命令执行效果说明：

  • ros2 pkg list

    列出当前 ROS2 环境中所有可见的包名，用来确认某个包是否已经安装或已经被工作空间识别。

  • ros2 pkg prefix <包名>

    输出某个包的安装前缀路径，通常可用来确认包来自系统安装还是来自本地工作空间。

  • ros2 pkg prefix --share <包名>

    输出包的 share 目录路径，通常用于查找配置文件、launch 文件、资源文件。

  • ros2 pkg executables <包名>

    列出该包内可直接运行的可执行程序名称，便于配合 ros2 run 启动节点。

6.3 节点相关


ros2 node list

ros2 node info <节点名>

ros2 run <包名> <可执行程序名>

命令执行效果说明：

  • ros2 node list

    列出当前系统中正在运行的 ROS2 节点名称，用来确认节点是否成功启动。

  • ros2 node info <节点名>

    查看某个节点的详细信息，包括它订阅了哪些 topic、发布了哪些 topic、提供了哪些 service、使用了哪些 action。

  • ros2 run <包名> <可执行程序名>

    直接启动一个包中的可执行节点程序，适合快速运行单个节点进行测试。

6.4 Topic 相关


ros2 topic list

ros2 topic list -t

ros2 topic info <topic名>

ros2 topic info -v <topic名>

ros2 topic echo <topic名>

ros2 topic echo <topic名> --once

ros2 topic hz <topic名>

ros2 topic bw <topic名>

ros2 topic pub <topic名> <消息类型> '<消息内容>'

命令执行效果说明：

  • ros2 topic list

    列出当前系统中所有正在存在的 topic 名称，用来判断某个话题是否已经发布出来。

  • ros2 topic list -t

    在列出 topic 名称的同时显示其消息类型，便于快速判断图像、IMU、TF 等话题的类型是否符合预期。

  • ros2 topic info <topic名>

    查看某个 topic 的基础信息，例如消息类型、发布者数量、订阅者数量。

  • ros2 topic info -v <topic名>

    查看某个 topic 的更详细信息，通常包括每个 publisher/subscriber 的 QoS 配置，适合排查通信不通、QoS 不匹配问题。

  • ros2 topic echo <topic名>

    持续输出该 topic 上收到的消息内容，适合检查数据是否在持续发布。

  • ros2 topic echo <topic名> --once

    只接收并打印一条消息，适合快速确认话题是否有数据而不刷屏。

  • ros2 topic hz <topic名>

    统计该 topic 的实际发布频率，适合检查图像帧率、IMU 频率、控制指令频率是否正常。

  • ros2 topic bw <topic名>

    统计该 topic 的带宽占用，适合评估图像流或点云流的数据量是否过大。

  • ros2 topic pub <topic名> <消息类型> '<消息内容>'

    手动向某个 topic 发布消息，常用于联调测试，例如手工发送字符串、位姿、速度命令等。

例子：


ros2 topic pub /chatter std_msgs/msg/String '{data: hello}'

执行效果：

  • 向 /chatter 这个 topic 发布一条 std_msgs/msg/String 类型的消息，内容为 hello。

  • 如果有节点订阅 /chatter，它就会收到这条测试消息。

6.5 Service 相关


ros2 service list

ros2 service list -t

ros2 service type <service名>

ros2 service find <服务类型>

ros2 service call <service名> <服务类型> '<请求内容>'

命令执行效果说明：

  • ros2 service list

    列出当前系统中所有可调用的 service 名称。

  • ros2 service list -t

    列出所有 service，并显示每个 service 对应的类型。

  • ros2 service type <service名>

    查看某个 service 使用的具体服务类型。

  • ros2 service find <服务类型>

    查找系统中有哪些 service 使用指定类型，适合根据接口反查服务名。

  • ros2 service call <service名> <服务类型> '<请求内容>'

    向某个 service 发送一次请求，并在终端中返回结果，适合触发清空地图、切换模式、重置状态等操作。

例子：


ros2 service call /clear std_srvs/srv/Empty '{}'

执行效果：

  • 调用 /clear 服务。

  • std_srvs/srv/Empty 表示该服务不需要请求参数。

  • 常见效果是触发一次“清空”类动作，例如清空缓存、清空代价地图或重置内部状态，具体行为由服务端实现决定。

6.6 Action 相关


ros2 action list

ros2 action list -t

ros2 action info <action名>

ros2 action send_goal <action名> <action类型> '<目标内容>'

命令执行效果说明：

  • ros2 action list

    列出当前系统中的所有 action 名称。

  • ros2 action list -t

    列出 action，并显示每个 action 对应的类型。

  • ros2 action info <action名>

    查看某个 action 的详细信息，例如 action 类型、服务端和客户端数量。

  • ros2 action send_goal <action名> <action类型> '<目标内容>'

    向 action 服务端发送一个目标任务，适合执行需要反馈过程和最终结果的操作，例如导航、轨迹执行、机械臂动作。

例子：


ros2 action send_goal /fibonacci example_interfaces/action/Fibonacci '{order: 10}'

执行效果：

  • 向 /fibonacci 这个 action 发送目标。

  • 请求服务端计算到第 10 项的 Fibonacci 序列。

  • 终端通常会显示目标是否被接受、执行过程反馈以及最终结果。

6.7 参数相关


ros2 param list

ros2 param list <节点名>

ros2 param get <节点名> <参数名>

ros2 param set <节点名> <参数名> <值>

ros2 param dump <节点名>

ros2 param load <节点名> <yaml文件>

命令执行效果说明：

  • ros2 param list

    列出系统中所有节点的参数，或者在支持时列出当前上下文可见的参数集合。

  • ros2 param list <节点名>

    列出指定节点的全部参数名。

  • ros2 param get <节点名> <参数名>

    读取某个节点当前使用的参数值。

  • ros2 param set <节点名> <参数名> <值>

    动态修改节点参数，前提是该参数支持运行时修改。

  • ros2 param dump <节点名>

    把该节点当前全部参数导出成 YAML 格式，适合留档或生成新配置。

  • ros2 param load <节点名> <yaml文件>

    从 YAML 文件向节点加载参数，适合批量恢复一组参数配置。

6.8 接口查看


ros2 interface list

ros2 interface show <接口名>

ros2 interface package <包名>

ros2 interface packages

命令执行效果说明：

  • ros2 interface list

    列出系统中所有可用的消息、服务、action 接口定义。

  • ros2 interface show <接口名>

    直接查看某个接口的字段定义，适合快速确认消息结构。

  • ros2 interface package <包名>

    查看某个接口包中定义了哪些消息、服务或 action。

  • ros2 interface packages

    列出当前环境里包含接口定义的所有包。

例子：


ros2 interface show sensor_msgs/msg/Image

执行效果：

  • 输出 sensor_msgs/msg/Image 的字段定义。

  • 你可以看到图像消息里包含 headerheightwidthencodingstepdata 等字段。

6.9 TF 相关


ros2 topic echo /tf

ros2 topic echo /tf_static

ros2 run tf2_ros tf2_echo <frame1> <frame2>

ros2 run tf2_ros static_transform_publisher x y z yaw pitch roll frame_id child_frame_id

命令执行效果说明：

  • ros2 topic echo /tf

    持续输出动态坐标变换，用于检查机器人、相机、底盘等坐标系之间是否在正常发布变换。

  • ros2 topic echo /tf_static

    输出静态坐标变换，用于检查固定安装关系是否存在，例如 base_link 到相机坐标系。

  • ros2 run tf2_ros tf2_echo

    直接查询两个坐标系之间当前的相对位姿变换。

  • ros2 run tf2_ros static_transform_publisher x y z yaw pitch roll frame_id child_frame_id

    手动发布一条静态坐标变换，常用于临时测试坐标关系是否正确。

例子：


ros2 run tf2_ros tf2_echo map base_link

ros2 run tf2_ros static_transform_publisher 0 0 0 0 0 0 map base_link

执行效果：

  • ros2 run tf2_ros tf2_echo map base_link

    实时显示 map 到 base_link 的相对位置和姿态。

  • ros2 run tf2_ros static_transform_publisher 0 0 0 0 0 0 map base_link

    发布一条静态 TF，表示 map 和 base_link 完全重合，没有平移和旋转。

6.10 Launch 相关


ros2 launch <包名> <launch文件>

ros2 launch <包名> <launch文件> --show-args

ros2 launch <包名> <launch文件> param_name:=value

命令执行效果说明：

  • ros2 launch <包名> <launch文件>

    启动一个 launch 文件，通常会同时拉起多个节点、参数和 remap 配置。

  • ros2 launch <包名> <launch文件> --show-args

    仅显示该 launch 文件支持的启动参数，不实际启动节点。

  • ros2 launch <包名> <launch文件> param_name:=value

    在启动时覆盖 launch 参数，便于切换配置文件、开关功能、设置设备路径。

6.11 Bag 相关


ros2 bag record <topic名>

ros2 bag record /topic1 /topic2

ros2 bag record -a

ros2 bag play <bag目录>

ros2 bag info <bag目录>

命令执行效果说明：

  • ros2 bag record <topic名>

    录制指定 topic 的数据，生成 ROS2 bag 文件。

  • ros2 bag record /topic1 /topic2

    同时录制多个指定 topic。

  • ros2 bag record -a

    录制当前系统中全部可见 topic，适合完整留档，但数据量可能很大。

  • ros2 bag play <bag目录>

    回放之前录制的 bag 数据，常用于离线调试算法。

  • ros2 bag info <bag目录>

    查看 bag 文件的摘要信息，例如包含哪些话题、消息数量、持续时间、存储格式等。

6.12 生命周期节点


ros2 lifecycle nodes

ros2 lifecycle get <节点名>

ros2 lifecycle set <节点名> configure

ros2 lifecycle set <节点名> activate

命令执行效果说明：

  • ros2 lifecycle nodes

    列出当前系统中采用生命周期管理模型的节点。

  • ros2 lifecycle get <节点名>

    查看某个生命周期节点的当前状态，例如 unconfiguredinactiveactive。

  • ros2 lifecycle set <节点名> configure

    把节点从未配置状态切换到已配置状态，通常会加载参数和初始化资源。

  • ros2 lifecycle set <节点名> activate

    把节点切换到激活状态，使其真正开始对外发布数据或响应请求。

6.13 图形调试工具


rqt_graph

ros2 run rqt_console rqt_console

ros2 run rqt_image_view rqt_image_view

rviz2

命令执行效果说明：

  • rqt_graph

    打开图形化节点拓扑图，显示节点与 topic 之间的连接关系。

  • ros2 run rqt_console rqt_console

    打开 ROS 日志查看器，用于查看不同节点输出的日志信息。

  • ros2 run rqt_image_view rqt_image_view

    打开图像查看工具，可以直接选择某个图像 topic 显示画面。

  • rviz2

    打开 RViz 可视化工具，用于显示图像、点云、TF、路径、标记等多种 ROS 数据。

6.14 工作空间构建


colcon build

colcon build --packages-select <包名>

colcon build --event-handlers console_direct+

source install/setup.bash

命令执行效果说明：

  • colcon build

    编译当前工作空间中的全部包。

  • colcon build --packages-select <包名>

    只编译指定包，适合改动范围较小时快速验证。

  • colcon build --event-handlers console_direct+

    编译时把日志直接输出到终端，便于查看报错发生的位置。

  • source install/setup.bash

    在编译结束后重新加载工作空间环境，使新编译的包和改动立即生效。

7. 当前项目最实用的调试命令

针对当前三目相机和 IMU 项目，最常用的是下面这些命令：


source install/setup.bash

ros2 node list

ros2 topic list -t

ros2 topic info /fays/atrak/cam_rgb

ros2 topic info /fays/atrak/cam_stereo

ros2 topic hz /fays/atrak/cam_rgb

ros2 topic hz /fays/atrak/cam_stereo

ros2 topic echo /fays/atrak/imu --once

ros2 run rqt_image_view rqt_image_view

rviz2

这一组命令足够覆盖：

  • 节点是否启动

  • 图像话题是否存在

  • 话题类型是否正确

  • 发布频率是否正常

  • IMU 是否正常出数

  • 图像是否能在 GUI 中显示

8. 总结

当前项目从 ROS topic 层面看，并不是直接发布三路独立图像，而是：

  • 一路中间 RGB/fays/atrak/cam_rgb

  • 一路双目统一输出/fays/atrak/cam_stereo

  • 一路 IMU/fays/atrak/imu

如果画面异常，优先排查：

  • 白平衡

  • 曝光/增益

  • 图像旋转

  • 设备权限和 udev 规则

  • /dev/video* 设备映射是否稳定

如果需要显示真正的三目独立画面，通常需要：

  • 修改驱动直接发布左目和右目 topic

  • 或新增一个拆分双目图像的 ROS2 节点