ROS Noetic/Melodic下，手把手教你将Qt Designer做的UI打包成Rviz插件
ROS Noetic/Melodic下Qt Designer UI转Rviz插件的完整实践指南
在机器人操作系统（ROS）生态中，Rviz作为可视化利器，其插件机制允许开发者扩展自定义功能。当遇到需要将Qt Designer设计的精美界面嵌入Rviz时，许多开发者会卡在Qt与ROS的版本适配、CMake配置等环节。本文将针对ROS Noetic（Qt5）和Melodic（Qt4）两个主流版本，详解从.ui文件到可加载插件的完整转化流程。
1. 环境准备与版本适配策略
开发Rviz插件前，必须明确工具链的版本依赖关系。ROS Noetic默认采用Qt5，而Melodic仍在使用Qt4，这种差异会导致编译环境和依赖配置的显著不同。
关键版本对照表：
| 组件 | ROS Noetic | ROS Melodic |
|---|---|---|
| Qt版本 | 5.12+ | 4.8.7 |
| CMake最低版本 | 3.0.2 | 2.8.3 |
| 编译器 | C++14 | C++11 |
| pluginlib接口 | 新版宏定义 | 传统宏定义 |
对于开发环境配置，建议：
- Noetic用户：直接安装
ros-noetic-rviz和qt5-default套件 - Melodic用户：需额外安装
qt4-default和ros-melodic-rviz，并注意：sudo apt-get install ros-melodic-qt-ros
提示：若同时安装多版本Qt，建议通过
qtchooser工具管理版本切换，避免环境冲突。
2. Qt Designer工程与ROS功能包联调
2.1 UI文件标准化处理
在Qt Designer中完成界面设计后，需特别注意：
- 主窗口类建议继承
QWidget而非QMainWindow，避免工具栏/状态栏的兼容性问题 - 控件命名遵循ROS惯例（如
velocity_slider而非horizontalSlider） - 保存.ui文件时选择与功能包同名的目录结构，例如：
~/catkin_ws/src/my_rviz_plugin/ui/ └── my_plugin.ui
2.2 功能包创建关键步骤
创建ROS功能包时，必须包含正确的依赖项：
catkin_create_pkg my_rviz_plugin roscpp rviz pluginlib qt_build对于文件结构的组织，推荐采用以下方式：
my_rviz_plugin/ ├── CMakeLists.txt ├── include/my_rviz_plugin/ │ └── my_plugin.h ├── src/ │ ├── my_plugin.cpp │ └── ui/ │ └── my_plugin.ui └── package.xml3. CMakeLists.txt深度配置解析
CMake配置是打通Qt与ROS的关键环节，不同版本需要针对性设置：
3.1 基础配置模板
# Noetic专用配置 set(CMAKE_AUTOUIC ON) # 自动处理UI文件 set(CMAKE_AUTOMOC ON) # 启用元对象编译器 set(CMAKE_AUTORCC ON) # 自动处理资源文件 find_package(catkin REQUIRED COMPONENTS rviz pluginlib ) if(${ROS_DISTRO} STREQUAL "noetic") find_package(Qt5 COMPONENTS Widgets REQUIRED) else() find_package(Qt4 REQUIRED) include(${QT_USE_FILE}) endif()3.2 关键编译指令
处理UI文件和源文件时需注意路径规范：
# 收集所有头文件和源文件 file(GLOB_RECURSE HEADERS include/${PROJECT_NAME}/*.h ) file(GLOB_RECURSE SOURCES src/*.cpp src/ui/*.ui ) # 创建共享库 add_library(${PROJECT_NAME} SHARED ${HEADERS} ${SOURCES} ) # 链接库依赖 target_link_libraries(${PROJECT_NAME} ${catkin_LIBRARIES} ${QT_LIBRARIES} )注意：Melodic用户需额外添加
${QT_QTCORE_LIBRARY}和${QT_QTGUI_LIBRARY}到链接库列表
4. 插件核心代码实现要点
4.1 头文件框架设计
插件类需要继承rviz::Panel并实现必要接口：
#ifndef MY_PLUGIN_H #define MY_PLUGIN_H #include <rviz/panel.h> #include <ui_my_plugin.h> // 由uic自动生成 namespace my_rviz_plugin { class MyPlugin : public rviz::Panel { Q_OBJECT public: MyPlugin(QWidget* parent = nullptr); virtual ~MyPlugin(); protected: // 必须实现的保存/加载配置方法 virtual void load(const rviz::Config& config); virtual void save(rviz::Config config) const; private: Ui::MyPluginUI ui_; // Qt Designer生成的UI类 }; } // namespace my_rviz_plugin #endif4.2 实现类关键逻辑
在.cpp文件中需要处理UI初始化和信号连接：
#include "my_rviz_plugin/my_plugin.h" namespace my_rviz_plugin { MyPlugin::MyPlugin(QWidget* parent) : rviz::Panel(parent) { // 设置UI主布局 ui_.setupUi(this); // 示例：连接信号槽 connect(ui_.start_button, &QPushButton::clicked, this, [this]() { ROS_INFO("Button clicked!"); }); } void MyPlugin::load(const rviz::Config& config) { // 加载配置参数 QString topic; if(config.getString("topic", &topic)) { ui_.topic_edit->setText(topic); } } void MyPlugin::save(rviz::Config config) const { // 保存当前配置 config.mapSetValue("topic", ui_.topic_edit->text()); } } // namespace5. 插件注册与部署实战
5.1 插件描述文件配置
创建plugin_description.xml文件：
<library path="lib/my_rviz_plugin"> <class name="MyPluginPanel" type="my_rviz_plugin::MyPlugin" base_class_type="rviz::Panel"> <description> 自定义控制面板，提供XXX功能 </description> </class> </library>5.2 package.xml关键配置
在package.xml中确保添加：
<export> <rviz plugin="${prefix}/plugin_description.xml" /> </export>5.3 编译与调试技巧
编译后若插件未显示，可按以下步骤排查：
- 检查插件是否被正确识别：
rospack plugins --attrib=plugin rviz - 查看运行时加载错误：
rviz --log-level-debug - 验证库路径是否正确：
ldd devel/lib/libmy_rviz_plugin.so
6. 跨版本兼容解决方案
针对不同ROS/Qt版本的特殊处理：
6.1 条件编译处理
在头文件中添加版本判断：
#if QT_VERSION >= 0x050000 #include <QtWidgets> #else #include <QtGui> #endif6.2 信号槽语法适配
对于Melodic的Qt4环境：
// Qt4风格的信号槽连接 connect(ui_.slider, SIGNAL(valueChanged(int)), this, SLOT(onSliderChanged(int)));而在Noetic中推荐使用新式语法：
// Qt5风格的信号槽连接 connect(ui_.slider, &QSlider::valueChanged, this, &MyPlugin::onSliderChanged);实际项目中，我发现在处理大型UI文件时，Qt5的元对象系统效率明显更高。某次将插件从Melodic迁移到Noetic后，界面响应速度提升了约30%，这得益于Qt5的信号槽机制优化。