前言
官网编译文档链接:
https://doc.percipio.xyz/cam/latest/getstarted/sdk-ros2-compile.html
国内gitee下载SDK链接:
https://gitee.com/percipioxyz
国外github下载SDK链接:
https://github.com/percipioxyz
1.Camport ROS2 SDK 介绍
1.1 Camport ROS2 SDK源文件介绍
Camport ROS2 SDK 的目录,目录包含了camport3,include,launch,src。
1.README.md:
简述了 ROS2 编译过程。
2.src/percipio_camera/CMakeLists.txt:
Cmake 编译系统的规则文件。
3.src/percipio_camera/camport3:
包含 Percipio SDK 的库文件和头文件。
4.src/percipio_camera/include:
包含头文件。
5.src/percipio_camera/launch:
包含 ROS2 的启动文件,用于启动节点和配置参数。
6.src/percipio_camera/package.xml:
描述功能包清单的文件,包括功能包的名称、版本号、作者信息、许可信息、编译依赖等。
7.src/percipio_camera/src:
包含主要的源代码文件,包括节点实现、相机驱动等。
1.2 Camport ROS2 SDK工作流程
1.2.1 包含头文件
包含必要的 ROS 2 头文件,例如 rclcpp。
1.2.2 2 初始化 ROS 2 节点
使用 rclcpp::init(argc, argv); 初始化 ROS 2。
1.2.3 创建节点对象
使用 rclcpp::Node::make_shared(“节点名称”) 创建节点对象。
1.2.4 创建发布者对象并实现发布逻辑
使用 node->create_publisher<消息类型>(“话题名称”, 队列大小);
创建发布者对象。实现发布逻辑,例如在回调函数中发布消息。
1.2.5 启动 ROS 2
使用 ros2 run 包名 节点名
运行指定的 ROS 2 节点。
使用 ros2 launch 包名 launch文件名
启动包含多个节点的 launch 文件。
1.3 ROS2 SDK环境配置与编译
主要针对ubuntu20.04对应ROS2 Foxy,以及ubuntu22.04对应ROS2 Humble两个版本的系统进行操作。
1.3.1 Ubuntu 20.04 下ROS2 Foxy环境配置与编译
环境配置与编译步骤:
第一步:设置编码
sudo apt update && sudo apt install locales
sudo locale-gen en_US en_US.UTF-8
sudo update-locale LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8
export LANG=en_US.UTF-8
第二步:添加ROS源的公钥
sudo apt update && sudo apt install curl gnupg lsb-release
sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg]
https://mirrors.tuna.tsinghua.edu.cn/ros2/ubuntu $(source /etc/os-release && echo $UBUNTU_CODENAME) main" | sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null
第三步:安装ROS2-foxy
sudo apt update
sudo apt upgrade
sudo apt install ros-foxy-desktop
sudo apt install python3-colcon-common-extensions
sudo apt install ros-foxy-camera-info-manager
sudo apt install ros-foxy-image-publisher
sudo apt install ros-foxy-diagnostic-updater
第四步:设置环境变量
source /opt/ros/foxy/setup.bash
echo " source /opt/ros/foxy/setup.bash" >> ~/.bashrc
第五步:camport3_ros2目录下,编译SDK
cd ~/ros2_ws/src/camport_ros2/
colcon build --event-handlers console_direct+ --cmake-args -DCMAKE_BUILD_TYPE=Release
sudo echo "source ./install/setup.bash" >> ~/.bashrc
source ~/.bashrc
colcon build 说明:
–event-handlers console_direct+:这个选项指定了事件处理程序。console_direct+ 表示直接在控制台输出构建事件的详细信息。这样可以更清楚地看到构建过程中的每一步和可能的错误信息。
–cmake-args -DCMAKE_BUILD_TYPE=Release:这个选项传递了额外的 CMake 参数。在这种情况下,-DCMAKE_BUILD_TYPE=Release 设置了 CMake 的构建类型为
Release。这意味着构建将进行优化,适合发布版本,而不是调试版本。
编译后会生成 build 文件夹(包含中间文件和目标文件)、install 文件夹(包括可执行文件、库文件、头文件和其他资源文件)和 log 文件夹(包含编译和运行时生成的日志文件)。
1.3.2 Ubuntu 22.04 下ROS2 Humble环境配置与编译
环境配置与编译步骤:
第一步:设置编码
sudo apt update && sudo apt install locales
sudo locale-gen en_US en_US.UTF-8
sudo update-locale LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8
export LANG=en_US.UTF-8
第二步:添加ROS源的公钥
sudo apt update && sudo apt install curl gnupg lsb-release
sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] https://mirrors.tuna.tsinghua.edu.cn/ros2/ubuntu $(source /etc/os-release && echo $UBUNTU_CODENAME) main" | sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null
第三步:安装ROS2-humble
sudo apt update
sudo apt upgrade
sudo apt install ros-humble-desktop
sudo apt install python3-colcon-common-extensions
sudo apt install ros-humble-camera-info-manager
sudo apt install ros-humble-image-publisher
sudo apt install ros-humble-diagnostic-updater
第四步:设置环境变量
source /opt/ros/ humble /setup.bash
echo " source /opt/ros/ humble /setup.bash" >> ~/.bashrc
第五步:camport3_ros2目录下,编译SDK
cd ~/ros2_ws/src/camport_ros2/
colcon build --event-handlers console_direct+ --cmake-args -DCMAKE_BUILD_TYPE=Release
sudo echo "source ./install/setup.bash" >> ~/.bashrc
source ~/.bashrc
colcon build 说明:
–event-handlers console_direct+:这个选项指定了事件处理程序。console_direct+ 表示直接在控制台输出构建事件的详细信息。这样可以更清楚地看到构建过程中的每一步和可能的错误信息。
–cmake-args -DCMAKE_BUILD_TYPE=Release:这个选项传递了额外的 CMake 参数。在这种情况下,-DCMAKE_BUILD_TYPE=Release 设置了 CMake 的构建类型为Release。这意味着构建将进行优化,适合发布版本,而不是调试版本。
1.3.3 编译文件检查
编译后会生成build,install,log。
1.build:
这个目录包含了编译过程中生成的中间文件和目标文件。包括对象文件(.o)、依赖文件等。 该目录在每次编译时都会被更新。
2.install:
这个目录包含了安装后的文件。包括可执行文件、库文件、头文件和其他资源文件。 该目录用于运行时使用,包含了所有需要的文件和依赖项。
3.log:
这个目录包含了编译和运行时生成的日志文件。包括编译日志、运行时日志和错误日志等。 这些日志文件对于调试和诊断问题非常有用。
2 参数配置
2.1 单相机
camport3_ros2/install/percipio_camera/share/percipio_camera/launch/percipio_camera.launch.py:
用于配置相机启动时加载的默认参数。如:指定相机的SN或IP、组件配置(配置color和depth的分辨率、ToF相关参数等)。
注意:当前连接相机的方式有两种:相机SN、相机IP。
2.2 percipio_camera.launch.py文件解析
1.触发属,建议根据实际情况设置
DeclareLaunchArgument('device_workmode', default_value='trigger_off'),#trigger_off / trigger_soft / trigger_hard
2.图像重传,建议设置为true,如不设置,网络状态较差时,容易丢帧。
DeclareLaunchArgument('gvsp_resend', default_value='true'),
注:该属性属于设备Device组建属性,无法保存进相机Storage区域,建议设置为true。
3.相机掉线重连,建议设置为true,相机掉线后,可自动重连。
DeclareLaunchArgument('device_auto_reconnect', default_value='true')
注:该属性属于设备Device组建属性,无法保存进相机Storage区域,建议设置为true。
4.TOF相机属性,这些属性可以保存进相机storage区域,可以不设置
DeclareLaunchArgument('tof_depth_quality', default_value='medium'), #basic / medium / high
DeclareLaunchArgument('tof_modulation_threshold', default_value='-1'),
DeclareLaunchArgument('tof_jitter_threshold', default_value='-1'),
DeclareLaunchArgument('tof_filter_threshold', default_value='-1'),
DeclareLaunchArgument('tof_channel', default_value='-1'),
DeclareLaunchArgument('tof_HDR_ratio', default_value='-1'),
2.3 多相机
camport3_ros2/install/percipio_camera/share/percipio_camera/launch/multi_cam.launch.py:
1.用于配置相机启动时加载的默认参数。如:指定相机的SN或IP、组件配置(配置color和depth的分辨率、ToF相关参数等)。
2.如果要添加第三台及以上,需要在下图红框处添加相关的代码,可以仿照第一、二台填写。
2.4 打开相机
第一步:
修改下面文件
camport3_ros2/install/percipio_camera/share/percipio_camera/launch/ percipio_camera.launch.py
然后发布
ros2 launch percipio_camera percipio_camera.launch.py
第二步:观察出图效果
2.4.1 方法一配置camera_ros.py
方法一:重新开一个终端,将camera_ros2.py复制到camport3_ros2目录下,并打开
camera_ros2.py
,进行编辑。修改下图内容中的红框为 launch中camera name参数的值。
执行命令:python3 ./camera_ros2.py ,下图为该程序的用法。
2.4.2 方法二使用RVIZ
方法二:重新开一个终端,运行Rviz(Robot Visualization),执行命令:
ros2 run rviz2 rviz2
1.打开RVIZ界面
2.配置深度图
3.打开深度图/彩色图/红外图
4.配置点云图并打开点云图
2.5 测试Camport ROS2 SDK
2.5.1 参数测试
支持配置的参数如下所示:
1.上述配置参数需在测试时自行添加至 launch中。
以添加color_format
为例,添加DeclareLaunchArgument(color_format',default_value='""');
之后修改default_value以设定图像格式。
2. xxx_format可配值,参考
/camport3_ros2/src/percipio_camera/src/percipio_device.cpp StreamFormatMapper format_mapper_list[]
2.5.2 相机测试
通过下表所列出的相机,测试不同组件的属性是否可以设置值,比如,Color组件下彩色相机的分辨率和格式;Depth组件下相机的分辨率和格式、ToF特有属性参数;IR组件下的相机的分辨率和格式等。
2.5.3 Storage 参数加载测试
ROS2 SDK支持打开相机后加载相机Storage配置参数,参数均可通过Percipio-viewer进行配置。测试方法如下:
1.确认相机的fetch_config.xml中有storage 组件。
2.使用Percipio-Viewer软件(支持保存相机参数的版本),打开相机,修改各个组件下Controls下的参数,然后保存参数到Storage。
3.使用ROS2打开相机,观察出图情况。
保存相机参数具体操作,可参考如下链接:
https://doc.percipio.xyz/cam/latest/viewermanual/operation.html#save-params-label
3.QoS策略说明
QoS(服务质量)策略是一种网络流量管理机制,用于控制和优化数据包的传输。
ROS2 可设置6种QoS 配置,其含义如下所示:
3.1 SYSTEM_DEFAULT
含义:ROS2系统的默认QoS配置(通常等同于 DEFAULT)。
适用场景:一般话题通信,无特殊需求时使用。
典型配置:
Reliability
: RELIABLE
Durability
: VOLATILE
History
: KEEP_LAST (depth=10)
3.2 DEFAULT
含义:ROS2推荐的默认QoS配置(与 SYSTEM_DEFAULT 类似)。
适用场景:适用于多数普通话题(如控制指令、状态信息)。
典型配置:
Reliability
: RELIABLE
Durability
: VOLATILE
History:
KEEP_LAST (depth=10)
3.3 PARAMETER_EVENTS
含义:用于参数动态更新的事件通信。
适用场景:当节点参数变化时,ROS2会通过该 QoS 发布事件通知。
典型配置:
Reliability
: RELIABLE
Durability
: VOLATILE
History
: KEEP_LAST (depth=1000)(参数变化可能较频繁,故历史深度较大)
3.4 SERVICES_DEFAULT
含义:ROS2服务(Service)的默认QoS。
适用场景:客户端-服务器(Service/Client)通信。
典型配置:
Reliability
: RELIABLE
Durability
: VOLATILE
History
: KEEP_LAST (depth=10)
3.5 PARAMETERS
含义:用于参数服务器(Parameter Server)通信。
适用场景:节点与参数服务器之间的交互(如 get_parameter/set_parameter)。
典型配置:
Reliability
: RELIABLE
Durability
: VOLATILE
History
: KEEP_LAST (depth=1000)
3.6 SENSOR_DATA
含义:传感器数据的高频、实时通信 QoS。
适用场景:摄像头、激光雷达、IMU 等传感器数据流。
典型配置:
Reliability
: BEST_EFFORT(允许丢包以降低延迟)
Durability
: VOLATILE
History
: KEEP_LAST (depth=10)
3.7 QoS配置对应的策略
两种Reliability 之间的区别如下:
3.8 在使用过程中该如何选择QoS配置?
1.需要低延迟(如实时图像传输) → SENSOR_DATA
2.需要可靠性(如关键配置信息) → DEFAULT 或 SYSTEM_DEFAULT
3.参数或服务通信 → 使用对应的专用配置。
4.ROS1加载相机参数
使用前提
:需要将相机SDK升级到3.6.66及以上版本
4.1 如何查看相机SDK版本?
打开如下链接
camport_ros2-main\src\percipio_camera\camport3\lib\linux\lib_x64
可以查看对应SDK版本
4.2 加载storage函数接口
在PV软件中进行保存参数后,运行官网版本的ROS2程序,程序会自动从相机Storage区读取保存的参数
4.3 额外属性设置
待补充
5.ROS2常见问题汇总
5.1 process has died -11报错
具体报错如下图3-1所示:
问题原因:之前的版本,矫正图像畸变,使用了opencv库, 在StreamDistortionMaplnit相关函数那里会报错,如出现此问题,可联系图漾技术更换去除opencv版本的SDK。
5.2 编译过程中缺少"camera info manager"
解决方式如下:
sudo apt-get install ros-foxy-camera-info-manager
5.3 编译过程中,提示缺少“image publisher”
这个是缺少ROS图像处理管道(image_pipeline)
安装即可,我的是ROS2-foxy,根据自己版本更改。
解决方式如下:
sudo apt install ros-foxy-image-pipeline
4.4 ROS2报错缺少“diagnostic_updater“,CMake did not find diagnostic_updater。
解决方式如下:
sudo apt install ros-foxy-diagnostic-updater