RViz2自定义Panel开发：从零构建交互式UI面板

张

张建站

2026/8/16 17:59:01

10分钟阅读

1. 为什么你需要一个自定义的RViz2面板如果你用过ROS2那肯定对RViz2不陌生。它是我们机器人开发者的“眼睛”激光雷达点云、机器人模型、导航路径什么都能看。但不知道你有没有过这样的感觉原生的RViz2面板功能是挺全可有时候就是不够用。比如我想一键切换多个机器人的显示配置或者想做一个专门控制自己开发的机械臂的快捷操作面板又或者想把一些关键的传感器数据用更酷的图表实时展示出来。这时候原生的按钮和菜单就显得有点捉襟见肘了。这就是自定义Panel的用武之地。你可以把它理解成给RViz2这个“毛坯房”做精装修加装你自己设计的智能家居控制面板。这个面板完全由你说了算想放什么按钮、滑块、图表、指示灯都行而且它能直接和ROS2的世界对话订阅话题、发布消息、调用服务样样精通。我做过一个项目需要同时监控四台移动机器人的电池状态和任务进度如果靠手动在RViz2里切换显示那简直是一场灾难。后来我花了两天时间做了个自定义面板把关键信息都聚合在一个视图里还加了几个一键下发任务的按钮效率提升了不止一倍。所以如果你觉得RViz2的标准界面限制了你的工作流或者你想为你的机器人系统打造一个更专业、更集成的调试和操作界面那么学习开发自定义Panel就是一个必选项。它不是什么高深莫测的黑科技本质上就是基于Qt框架做UI开发再通过ROS2的接口和后台数据打通。接下来我就带你从零开始手把手构建一个真正有用的交互式面板而不仅仅是显示一个“Hello World”。2. 搭建你的开发环境从零开始的准备工作工欲善其事必先利其器。开发RViz2自定义面板其实就是在开发一个ROS2包只不过这个包的特殊之处在于它生成的是一个能被RViz2动态加载的Qt插件。所以我们的起点是一个干净的ROS2工作空间。我假设你已经安装了ROS2推荐Humble或Iron版本并且对基本的ROS2命令如创建包、编译有初步了解。首先我们创建一个专门的工作空间。我习惯把所有实验性的开发都放在一个独立的dev_ws里这样不会污染主要的工作环境。打开终端执行mkdir -p ~/dev_ws/src cd ~/dev_ws/src接下来创建我们的面板包。这里有个关键点包的类型必须是ament_cmake因为我们需要CMake来管理复杂的Qt和插件编译过程。同时要声明对rviz_common的依赖这是RViz2的核心库。ros2 pkg create rviz2_custom_panel --build-type ament_cmake --dependencies rviz_common命令执行后你会看到一个名为rviz2_custom_panel的文件夹被创建出来。进去看看它的结构你会发现标准的CMakeLists.txt和package.xml已经在了。但这还不够我们需要为Qt开发做准备。虽然我们在创建包时只声明了rviz_common依赖但Qt5的依赖我们稍后会在CMakeLists.txt里显式地查找和链接。这是因为RViz2本身基于Qt所以你的系统肯定已经安装了Qt我们只需要告诉CMake去用就行了。在开始写代码前我强烈建议你花几分钟检查一下package.xml文件。用文本编辑器打开它你会看到ROS2自动生成了一些基础信息。我们需要确保dependrviz_common/depend这一行存在。你还可以补充一下包的描述和维护者信息虽然不影响编译但这是个好习惯。我的package.xml依赖部分看起来是这样的dependrviz_common/depend dependrclcpp/depend dependstd_msgs/depend我额外添加了rclcpp和std_msgs。为什么因为一个只会显示静态文字的面板是没灵魂的。我计划让我们的面板能够与ROS2系统交互比如订阅一个话题来显示消息或者发布一个消息来控制机器人。所以提前把这些常见的ROS2客户端库和消息依赖加进去后面用起来就顺手了。环境准备这一步看似简单但把地基打牢后面写代码和编译时才能避免很多莫名其妙的错误。我曾经因为忘了在package.xml里加某个依赖导致编译链接失败排查了半个多小时这个坑希望大家能避开。3. 创建你的第一个面板从“Hello World”到可运行插件好了环境就绪现在让我们动手创建面板的核心——C类。这个过程就像是制作一个乐高模块我们要先定义这个模块的蓝图头文件然后用零件把它拼出来源文件最后告诉乐高系统RViz2怎么找到和使用这个新模块插件描述。3.1 编写面板类的头文件首先在包的include目录下创建头文件。我把它命名为interactive_panel.h这比简单的rviz2_panel.h更能体现我们的目标。#pragma once // 核心必须继承自 rviz_common::Panel #include rviz_common/panel.hpp // 引入Qt信号槽机制的头文件 #include QPushButton #include QLabel #include QLineEdit // 使用命名空间防止命名冲突 namespace rviz2_custom_panel { class InteractivePanel : public rviz_common::Panel { // 注意所有使用信号槽的Qt类都必须包含 Q_OBJECT 宏 Q_OBJECT public: // 构造函数父部件默认为nullptr explicit InteractivePanel(QWidget * parent nullptr); // 析构函数使用默认实现 ~InteractivePanel() override default; // 可选重写Panel的加载/保存配置函数用于持久化面板状态 void load(const rviz_common::Config config) override; void save(rviz_common::Config config) const override; // 声明一个受保护的区域用于放置未来可能用到的内部函数或变量 protected: // 声明UI部件指针 QLabel * status_label_; QPushButton * action_button_; QLineEdit * topic_edit_; // 私有槽函数区域用于响应UI交互 private Q_SLOTS: // 当按钮被点击时调用的槽函数 void onButtonClicked(); }; } // namespace rviz2_custom_panel我来解释一下关键点。第一类必须公开继承rviz_common::Panel这是所有RViz2面板的基类。第二Q_OBJECT宏绝对不能少它让Qt的元对象编译器MOC能够处理这个类中的信号和槽这是实现交互的基石。第三我声明了几个Qt部件指针一个用于显示状态的标签一个触发动作的按钮还有一个输入话题名的文本框。第四我声明了一个槽函数onButtonClicked它将与按钮的clicked()信号连接。最后我重写了load和save虚函数虽然这个简单例子用不到但这是一个好习惯为将来保存面板的布局或设置比如记住上次输入的话题名预留了接口。3.2 实现面板类的源文件接下来在src目录下创建interactive_panel.cpp实现头文件中声明的函数。#include interactive_panel.hpp // 引入Qt布局和ROS2相关头文件 #include QVBoxLayout #include QHBoxLayout #include rclcpp/rclcpp.hpp #include std_msgs/msg/string.hpp namespace rviz2_custom_panel { // 构造函数在这里创建UI并布局 InteractivePanel::InteractivePanel(QWidget * parent) : rviz_common::Panel(parent) // 调用基类构造函数 { // 1. 创建UI部件 status_label_ new QLabel(状态: 等待输入, this); status_label_-setAlignment(Qt::AlignCenter); status_label_-setStyleSheet(QLabel { font-weight: bold; color: #555; }); action_button_ new QPushButton(发布问候, this); topic_edit_ new QLineEdit(this); topic_edit_-setPlaceholderText(输入话题名例如/greeting); // 2. 创建布局管理器并添加部件 QVBoxLayout * main_layout new QVBoxLayout(this); QHBoxLayout * input_layout new QHBoxLayout(); input_layout-addWidget(new QLabel(目标话题:, this)); input_layout-addWidget(topic_edit_); main_layout-addWidget(status_label_); main_layout-addLayout(input_layout); main_layout-addWidget(action_button_); main_layout-addStretch(); // 添加一个弹性空间让UI顶部对齐 // 3. 设置当前Widget的布局 this-setLayout(main_layout); // 4. 连接信号与槽当按钮被点击调用 onButtonClicked 函数 connect(action_button_, QPushButton::clicked, this, InteractivePanel::onButtonClicked); // 5. 初始化ROS2节点注意RViz2插件使用其自身的节点 // 这里先不创建发布者等用户点击按钮时再根据输入的话题名创建 } // 按钮点击的槽函数实现 void InteractivePanel::onButtonClicked() { QString topic_name topic_edit_-text().trimmed(); if (topic_name.isEmpty()) { status_label_-setText(状态: 错误 - 话题名不能为空); status_label_-setStyleSheet(QLabel { color: #d00; }); return; } // 在实际项目中这里应该使用RViz2提供的节点上下文来创建发布者避免节点冲突。 // 为了示例清晰我们简化处理每次点击都创建一个一次性节点并发布消息。 // 注意这不是最佳实践仅用于演示交互逻辑。 auto node std::make_sharedrclcpp::Node(temp_publisher_node); auto publisher node-create_publisherstd_msgs::msg::String(topic_name.toStdString(), 10); std_msgs::msg::String msg; msg.data Hello from RViz2 Custom Panel!; publisher-publish(msg); status_label_-setText(状态: 已向话题 [ topic_name ] 发布消息); status_label_-setStyleSheet(QLabel { color: #080; }); // 短暂延迟后恢复状态 QTimer::singleShot(2000, this, [this]() { status_label_-setText(状态: 等待输入); status_label_-setStyleSheet(QLabel { color: #555; }); }); } // 加载配置暂为空实现 void InteractivePanel::load(const rviz_common::Config config) { (void) config; // 避免未使用参数警告 } // 保存配置暂为空实现 void InteractivePanel::save(rviz_common::Config config) const { (void) config; } } // namespace rviz2_custom_panel // 插件声明宏这是将此类注册为RViz2插件的关键 #include pluginlib/class_list_macros.hpp PLUGINLIB_EXPORT_CLASS(rviz2_custom_panel::InteractivePanel, rviz_common::Panel)这个实现比一个简单的“Hello World”丰富多了。在构造函数里我们不仅创建了部件还用QVBoxLayout和QHBoxLayout进行了基本的布局管理让界面看起来更整齐。connect函数是Qt信号槽机制的灵魂它把按钮的clicked()信号和我们自定义的onButtonClicked()槽函数绑定在一起。槽函数onButtonClicked是交互的核心。它做了几件事获取用户输入的话题名进行简单的非空校验然后动态创建一个ROS2节点和发布者向指定话题发布一条问候消息最后更新UI状态标签给用户视觉反馈并用QTimer::singleShot在2秒后恢复初始状态。这里关于ROS2节点的创建方式我做了简化在真正的RViz2插件开发中更推荐通过rviz_common::RosNodeAbstraction等方式来安全地使用ROS2功能避免节点命名冲突。但为了首次接触的你能更直观地理解“点击-发布”这个完整链路我采用了这种直白的方式。最后注意文件末尾的PLUGINLIB_EXPORT_CLASS宏。这行代码至关重要它利用pluginlib工具将我们的类导出为一个插件。没有它RViz2就找不到你的面板。4. 配置构建系统让CMake和ROS2认识你的插件代码写好了但我们现在有一堆.cpp和.hpp文件计算机不知道该怎么把它们变成RViz2能加载的库。这就需要配置构建系统主要是CMakeLists.txt和package.xml。很多新手在这里栽跟头因为涉及Qt的编译有些特殊步骤。4.1 配置CMakeLists.txt打开包根目录下的CMakeLists.txt我们需要对它进行大幅修改。别怕我一步步解释。cmake_minimum_required(VERSION 3.8) # 建议使用3.8或更高对C14/17支持更好 project(rviz2_custom_panel) # 1. 查找必需的依赖包 find_package(ament_cmake REQUIRED) find_package(rviz_common REQUIRED) find_package(rclcpp REQUIRED) # 因为我们用了ROS2客户端库 find_package(std_msgs REQUIRED) # 因为我们用了std_msgs消息 # 2. 查找Qt5组件。Widgets是构建UI所必须的。 find_package(Qt5 COMPONENTS Widgets Core REQUIRED) # 3. 设置包含目录让编译器能找到我们的头文件 include_directories( include ${Qt5Widgets_INCLUDE_DIRS} ) # 4. 关键步骤使用Qt的宏来处理包含Q_OBJECT的头文件。 # 这会将头文件生成对应的moc_*.cpp文件用于信号槽机制。 qt5_wrap_cpp(MOC_FILES include/interactive_panel.hpp ) # 5. 设置要编译的源文件列表 set(SOURCE_FILES src/interactive_panel.cpp ${MOC_FILES} # 必须将生成的moc文件也加入源文件列表 ) # 6. 创建共享库动态链接库这就是我们的插件 add_library(${PROJECT_NAME} SHARED ${SOURCE_FILES} ) # 7. 为目标库链接所需的库文件 target_link_libraries(${PROJECT_NAME} Qt5::Widgets Qt5::Core ${rviz_common_LIBRARIES} rclcpp::rclcpp std_msgs::std_msgs ) # 8. 为库添加依赖项 ament_target_dependencies(${PROJECT_NAME} rviz_common rclcpp std_msgs ) # 9. 安装规则将编译好的库安装到install目录下的lib文件夹中 install(TARGETS ${PROJECT_NAME} ARCHIVE DESTINATION lib LIBRARY DESTINATION lib RUNTIME DESTINATION bin ) # 10. 安装头文件虽然不是必须但好习惯 install(DIRECTORY include/ DESTINATION include/${PROJECT_NAME} ) # 11. 最关键的一步导出插件描述文件。 # 这行命令会确保我们的 plugin_description.xml 文件被安装到正确的位置 # 并被ROS2的插件系统索引到。 pluginlib_export_plugin_description_file(rviz_common plugin_description.xml) ament_package()让我强调几个最容易出错的地方。第一qt5_wrap_cpp(MOC_FILES ...)这一行必须要有并且参数是你的头文件路径。如果漏了编译可能会通过但运行时信号槽完全不起作用按钮点了没反应你会百思不得其解。第二set(SOURCE_FILES ...)时一定要把${MOC_FILES}加进去否则生成的moc代码不会被编译。第三target_link_libraries里Qt5::Widgets和Qt5::Core是链接Qt库${rviz_common_LIBRARIES}是链接RViz2库后面两个是链接ROS2的库。链接器如果找不到符号多半是这里漏了。4.2 创建插件描述文件在包的根目录和CMakeLists.txt同级创建一个名为plugin_description.xml的文件。这个文件是插件的“身份证”告诉RViz2去哪里加载这个库以及库里面有什么可用的类。library pathrviz2_custom_panel class namerviz2_custom_panel/InteractivePanel typerviz2_custom_panel::InteractivePanel base_class_typerviz_common::Panel description 这是一个交互式自定义面板示例。它可以向用户指定的ROS2话题发布问候消息。 /description /class /librarylibrary path指定库的名字不含前缀lib和后缀.so也就是我们CMake项目中add_library的目标名${PROJECT_NAME}。class name这是插件在RViz2的“Add New Panel”对话框中显示的名字。你可以用/来分组例如MyTools/GreetingPanel。class type完整的C类名包括命名空间。base_class_type必须为rviz_common::Panel。至此项目的核心结构就完成了。你的包目录应该看起来像这样rviz2_custom_panel/ ├── CMakeLists.txt ├── include │ └── interactive_panel.hpp ├── package.xml ├── plugin_description.xml └── src └── interactive_panel.cpp5. 构建、运行与调试看到你的成果最激动人心的时刻到了我们要把代码变成实际可用的面板。5.1 编译你的包回到工作空间根目录使用colcon进行编译。我强烈建议在第一次编译时只编译我们这个包这样更快也更容易定位错误。cd ~/dev_ws colcon build --packages-select rviz2_custom_panel --symlink-install这里我用了--symlink-install参数。它会在install目录下创建符号链接而不是复制文件。这样你在src目录下修改了源代码后无需重新install直接重新编译colcon build即可生效对于开发调试非常方便。编译过程可能会花一两分钟。如果成功你会在最后看到类似“Summary: X packages finished”的字样。如果失败请仔细查看错误信息。常见的错误包括找不到头文件检查CMakeLists.txt的include_directories和依赖声明、链接错误检查target_link_libraries、或者Qt的moc问题检查qt5_wrap_cpp和源文件是否包含Q_OBJECT。5.2 在RViz2中加载你的面板编译成功后需要让当前终端环境知道这个新插件。source ~/dev_ws/install/setup.bash然后启动RViz2rviz2RViz2启动后按照以下步骤找到你的面板点击RViz2左上角的菜单栏Panels。在下拉菜单中选择Add New Panel...。这时会弹出一个对话框里面列出了所有可用的面板。你应该能在列表中找到rviz2_custom_panel/InteractivePanel或者你定义的class name。选中它。点击OK。你的自定义面板应该会出现在RViz2的界面中默认位置可能在左侧或底部。你可以用鼠标拖动它的标题栏把它停靠在你喜欢的任何位置上、下、左、右或浮动。5.3 测试交互功能现在来玩一下我们做的面板在面板的文本输入框里填写一个ROS2话题名例如/my_greeting。点击发布问候按钮。观察面板上的状态标签应该会变成绿色显示“状态: 已向话题 [/my_greeting] 发布消息”。同时你可以打开另一个终端用ROS2的命令监听这个话题验证消息是否真的发出去了source /opt/ros/humble/setup.bash # 根据你的ROS2版本调整 ros2 topic echo /my_greeting你应该能看到终端里打印出data: Hello from RViz2 Custom Panel!这条消息。看到这里恭喜你你已经成功创建了一个能与ROS2世界交互的、真正的自定义RViz2面板。6. 进阶之路让面板变得更实用一个能发布消息的面板已经是个不错的开始但这只是冰山一角。要让面板真正在项目中发挥作用我们还需要考虑更多。6.1 实现配置的持久化你可能会注意到每次关闭RViz2再打开面板里输入的话题名就清空了。在实际使用中我们可能希望记住上次的设置。这就需要用到我们之前重写的load和save函数。这两个函数使用rviz_common::Config对象本质上是YAML格式来读写配置。我们可以在save函数中将当前的话题名保存起来void InteractivePanel::save(rviz_common::Config config) const { Panel::save(config); config.mapSetValue(TopicName, topic_edit_-text()); }在load函数中读取并恢复void InteractivePanel::load(const rviz_common::Config config) { Panel::load(config); QString topic_name; if (config.mapGetString(TopicName, topic_name)) { topic_edit_-setText(topic_name); } }这样你的面板状态就能在RViz2会话之间保持了。6.2 安全地集成ROS2节点我们之前的例子中每次点击按钮都创建一个新节点这非常不优雅而且可能造成节点名冲突。在RViz2插件中正确的方式是使用RViz2提供的节点接口。通常你可以通过getDisplayContext()-getRosNodeAbstraction()来获取一个共享的ROS2节点抽象对象然后用它来创建发布者、订阅者等。这确保了所有插件都通过RViz2主节点进行通信管理起来更清晰、更安全。这部分涉及更多RViz2内部API在你熟悉基础开发后查阅RViz2的官方源码或高级教程是下一步的方向。6.3 设计更复杂的UI和交互Qt提供了无比丰富的控件组合框QComboBox、滑块QSlider、表格QTableWidget、图表QChartView等等。你可以根据你的机器人应用场景来组合它们。例如做一个显示机器人实时速度曲线的图表面板或者做一个可以拖拽滑块来控制机械臂关节角度的控制面板。关键在于理解信号槽机制将UI控件的变化信号与你希望执行的ROS2操作槽函数紧密连接起来。开发过程中你可能会遇到界面布局混乱的问题。这时候不要硬编码控件的位置和大小一定要用好Qt的布局管理器QHBoxLayout,QVBoxLayout,QGridLayout。它们能自动调整控件的大小和位置适应面板大小的变化。另外使用Qt Designer工具来可视化地设计.ui文件再通过Qt的uic工具集成到代码中可以极大地提升复杂界面的开发效率。这需要你在CMakeLists.txt中额外配置find_package(Qt5 COMPONENTS Widgets UiTools REQUIRED)并使用qt5_wrap_ui命令网上有很多相关教程。从我自己的经验来看开发自定义面板最大的“坑”往往不是ROS2部分而是对Qt框架的不熟悉。花点时间学习Qt的基本概念比如父子对象关系、内存管理Qt的半自动内存管理、布局、事件循环会让你在开发过程中事半功倍。当你第一次做出一个能流畅控制机器人、并漂亮地显示各种状态的面板时那种成就感和效率的提升会让你觉得这些投入都是值得的。