本文档整理了当前项目中涉及的相机配置说明、视频异常现象分析、三目画面显示方法，以及 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 当前参数：
```yaml
awb: true
rgb_white_balance_r: 1.3
rgb_white_balance_g: 0.8
rgb_white_balance_b: 2.1
```
可能的问题：
- 自动白平衡没有稳定下来
- 驱动在自动白平衡开启时仍参考手动增益
- 环境光源复杂，导致 AWB 判断失准
#### 曝光和增益偏高
双目当前参数：
```yaml
stereo_init_exposure: -1
stereo_gain_value: -1
```
这表示自动曝光和自动增益参与控制，强光环境下容易过曝。
#### 图像方向不对
如果相机是倒装的，而 rgb_rotate: 0，画面就会方向异常。
### 2.2 推荐排查顺序
建议不要一次改很多参数，而是按顺序测试。
#### 第一步：先处理中间 RGB 偏色
先尝试关闭自动白平衡，并把手动白平衡恢复到中性值：
```yaml
awb: false
rgb_white_balance_r: 1.0
rgb_white_balance_g: 1.0
rgb_white_balance_b: 1.0
```
如果画面明显正常很多，说明问题主要来自白平衡。
然后可以小幅微调，例如：
```yaml
rgb_white_balance_r: 1.1
rgb_white_balance_g: 1.0
rgb_white_balance_b: 1.1
```
#### 第二步：如果图像方向不对，修改旋转
```yaml
rgb_rotate: 180
```
这只解决上下翻转，不解决物理斜装。
#### 第三步：如果显示的是双目图像，再调双目参数
保守调试版本可先设为：
```yaml
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 建议优先试的最小改动
优先只改这几行：
```yaml
awb: false
rgb_white_balance_r: 1.0
rgb_white_balance_g: 1.0
rgb_white_balance_b: 1.0
```
如果方向不对，再加：
```yaml
rgb_rotate: 180
```
## 3. 为什么重新执行 FTDI 权限脚本会恢复正常
相关脚本的作用通常包括：
- 检测 FTDI Superspeed Video Bridge 设备
- 生成 udev 规则
- 重新加载规则
- 触发设备重新匹配
- 把用户加入 video 和 plugdev 组
### 3.1 重新执行脚本后恢复的常见原因
#### 规则第一次没有及时生效
可能流程是：
1. 设备先插入并创建设备节点
2. 此时规则还没写入或未 reload
3. 节点权限不对
4. 重新执行脚本后udevadm trigger 让规则真正生效
#### 用户组修改不会立刻影响当前终端
脚本中的：
```bash
sudo usermod -a -G video,plugdev $USER
```
不会立刻让当前 shell 拥有新组权限，通常需要重新登录或打开新的会话。
#### 设备节点顺序发生变化
当前配置写死了：
```yaml
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 输出：
```text
[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，相关话题为：
```text
/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 类型
```bash
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 环境相关
```bash
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 包相关
```bash
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 节点相关
```bash
ros2 node list
ros2 node info <节点名>
ros2 run <包名> <可执行程序名>
```
命令执行效果说明：
- ros2 node list
列出当前系统中正在运行的 ROS2 节点名称，用来确认节点是否成功启动。
- ros2 node info <节点名>
查看某个节点的详细信息，包括它订阅了哪些 topic、发布了哪些 topic、提供了哪些 service、使用了哪些 action。
- ros2 run <包名> <可执行程序名>
直接启动一个包中的可执行节点程序，适合快速运行单个节点进行测试。
### 6.4 Topic 相关
```bash
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 发布消息，常用于联调测试，例如手工发送字符串、位姿、速度命令等。
例子：
```bash
ros2 topic pub /chatter std_msgs/msg/String '{data: hello}'
```
执行效果：
- 向 /chatter 这个 topic 发布一条 std_msgs/msg/String 类型的消息，内容为 hello。
- 如果有节点订阅 /chatter，它就会收到这条测试消息。
### 6.5 Service 相关
```bash
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 发送一次请求，并在终端中返回结果，适合触发清空地图、切换模式、重置状态等操作。
例子：
```bash
ros2 service call /clear std_srvs/srv/Empty '{}'
```
执行效果：
- 调用 /clear 服务。
- std_srvs/srv/Empty 表示该服务不需要请求参数。
- 常见效果是触发一次“清空”类动作，例如清空缓存、清空代价地图或重置内部状态，具体行为由服务端实现决定。
### 6.6 Action 相关
```bash
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 服务端发送一个目标任务，适合执行需要反馈过程和最终结果的操作，例如导航、轨迹执行、机械臂动作。
例子：
```bash
ros2 action send_goal /fibonacci example_interfaces/action/Fibonacci '{order: 10}'
```
执行效果：
- 向 /fibonacci 这个 action 发送目标。
- 请求服务端计算到第 10 项的 Fibonacci 序列。
- 终端通常会显示目标是否被接受、执行过程反馈以及最终结果。
### 6.7 参数相关
```bash
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 接口查看
```bash
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
列出当前环境里包含接口定义的所有包。
例子：
```bash
ros2 interface show sensor_msgs/msg/Image
```
执行效果：
- 输出 sensor_msgs/msg/Image 的字段定义。
- 你可以看到图像消息里包含 headerheightwidthencodingstepdata 等字段。
### 6.9 TF 相关
```bash
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 <frame1> <frame2>
直接查询两个坐标系之间当前的相对位姿变换。
- ros2 run tf2_ros static_transform_publisher x y z yaw pitch roll frame_id child_frame_id
手动发布一条静态坐标变换，常用于临时测试坐标关系是否正确。
例子：
```bash
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 相关
```bash
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 相关
```bash
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 生命周期节点
```bash
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 图形调试工具
```bash
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 工作空间构建
```bash
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 项目，最常用的是下面这些命令：
```bash
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 节点
Fays Vikit ROS2 相机配置与调试说明
本文采用 CC BY-NC-SA 4.0 许可协议，转载请注明出处。
评论交流
欢迎留下你的想法