ROS 2 平台

ROS 2（Robot Operating System 2）是机器人操作系统的第二代版本。它是一个开源的机器人软件框架，旨在为机器人开发提供工具和库，以简化机器人应用的创建和管理。ROS 2 是由 Open Robotics 开发和维护的，继承了 ROS 1 的许多优点，同时在架构和功能上进行了改进，以满足现代机器人系统的需求。

搭建 ROS 2 开发环境

根据 Ubuntu 版本，安装对应的 ROS 2 开发平台。
- Ubuntu20.04：ROS 2 Foxy
- Ubuntu22.04：ROS 2 Humble

安装依赖。

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

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/foxy/setup.bash
echo "source /opt/ros/foxy/setup.bash" >> ~/.bashrc

source /opt/ros/humble/setup.bash
echo "source /opt/ros/humble/setup.bash" >> ~/.bashrc

下载 Camport ROS 2 SDK

创建工作目录

mkdir -p ~/ros2_ws/src
cd ~/ros2_ws/src/

下载 Camport ROS 2

选择以下任意方式，下载 Camport ROS 2 SDK：
使用浏览器下载： https://gitee.com/percipioxyz/camport_ros2.git。
使用 git 指令获取本地副本：打开终端，切换到需存放 SDK 的工作目录下，输入 git clone 命令克隆远程仓库。
git clone https://gitee.com/percipioxyz/camport_ros2.git
选择以下任意方式，下载 Camport ROS 2 SDK：
使用浏览器下载：https://github.com/percipioxyz/camport_ros2.git。
使用 git 指令获取本地副本：打开终端，切换到需存放 SDK 的工作目录下，输入 git clone 命令克隆远程仓库。
git clone https://github.com/percipioxyz/camport_ros2.git

Camport ROS 2 SDK 的目录如下图所示：

camport_ros2/
├── 📂 src/                           # ROS 2 源码目录
│   └── 📂 percipio_camera/          # ROS 2 相机驱动包
│       ├── 📂 camport4/             # Camport4 SDK集成
│       ├── 📂 include/              # 头文件目录
│       ├── 📂 launch/               # ROS 2 启动配置文件
│       ├── 📂 src/                  # C++源文件目录
│       ├── 📄 CMakeLists.txt        # CMake构建配置文件
│       └── 📄 package.xml           # ROS 2 包定义文件
└── 📄 README.md                      # ROS 2 编译说明文档

src/percipio_camera/camport4：包含 Percipio SDK 的库文件和头文件。
src/percipio_camera/include：包含头文件。
src/percipio_camera/launch：包含 ROS 2 的启动文件，用于启动节点和配置参数，其中 percipio_camera.launch.py 用于启动单相机， multi_cam.launch.py 用于启动多相机。此外，包内包含的多个 Python 脚本可分别用于订阅节点并显示图像数据、发送软触发信号、离线检测等，详情请参见订阅相机节点。
src/percipio_camera/src：包含主要的源代码文件，包括节点实现、相机驱动等。
src/percipio_camera/CMakeLists.txt：Cmake 编译系统的规则文件。
src/percipio_camera/package.xml：描述功能包清单的文件，包括功能包的名称、版本号、作者信息、许可信息、编译依赖等。
README.md：简述了 ROS 2 编译过程。

编译

cd ~/ros2_ws/src/camport_ros2/
colcon build --event-handlers  console_direct+  --cmake-args  -DCMAKE_BUILD_TYPE=Release

小技巧

colcon build 说明：

--event-handlers console_direct+：这个选项指定了事件处理程序。console_direct+ 表示直接在控制台输出构建事件的详细信息。这样可以更清楚地看到构建过程中的每一步和可能的错误信息。
--cmake-args -DCMAKE_BUILD_TYPE=Release：这个选项传递了额外的 CMake 参数。在这种情况下，-DCMAKE_BUILD_TYPE=Release 设置了 CMake 的构建类型为 Release。这意味着构建将进行优化，适合发布版本，而不是调试版本。

编译后生成以下文件夹：

build ：中间文件和目标文件。
install ：可执行文件、库文件、头文件和其他资源文件。
log ：包含编译和运行时生成的日志文件。

配置环境变量

sudo echo "source ./install/setup.bash" >> ~/.bashrc
source ~/.bashrc

修改参数配置

ROS 2 支持通过以下三种方式修改相机参数。

方法一：通过 Viewer 软件提前设置参数并保存至相机（推荐）

GigE2.1 相机（PMD 系列与 GM 系列相机）

通过 Viewer 软件将参数设置保存至 UserSet 属性组，并将该组设置为默认加载的 User Set 属性组，相机上电后将自动加载该 User Set 属性组的参数配置。
GigE2.0 相机（除 PMD 系列与 GM 系列以外的相机）

通过 Percipio Viewer 软件将参数设置保存至相机 Storage 区，ROS 启动时将自动加载 storage 区的参数配置并开始采集图像。

方法二：编辑 launch.py 配置文件

在 percipio_camera.launch.py / multi_cam.launch.py 中配置相机节点启动时加载的参数。该方法仅适用于设置文件中包含的参数，具体步骤如下：

进入 “camport_ros2/install/percipio_camera/share/percipio_camera/launch” 路径。
修改参数配置。

如使用单台相机，打开 percipio_camera.launch.py 文件，并根据需要修改参数配置。

示例：指定相机
指定相机 SN 号
DeclareLaunchArgument('serial_number', default_value='"207000106930"'),
指定相机 IP 地址
DeclareLaunchArgument('device_ip', default_value='192.168.120.112'),
注解

如果不通过 SN 或 IP 去指定相机，默认打开找到的第一台相机。

更多参数配置说明，请参见下表。
如使用多台相机，打开 multi_cam.launch.py 文件，并根据需要修改参数配置。

multi_cam.launch.py 文件默认是配置两台相机，如需配置更多相机，请仿照 launch 1、launch2 的内容添加 launch x (x=3,4……n)。

关于参数配置说明，请参见下表。
launch.py 可配置参数表

参数名

描述

取值范围

camera_name

节点名

自定义，多相机情况下可通过该名称区分相机

serial_number

相机 SN 号

可为空；也可填写待连接相机的 SN 号

device_ip

相机 IP 地址

可为空；也可填写待连接相机的 IP 地址

device_log_enable

SDK日志的开关

true/false

device_log_level

SDK日志的等级

VERBOSE / DEBUG / INFO / WARNING / ERROR / NEVER

device_log_server_port

SDK日志服务器端口

默认值：9001

frame_rate_control

帧率控制开关

true/false

frame_rate

设置出图帧率

浮点型，默认值：5.0

device_workmode

相机触发模式

trigger_off/trigger_soft/trigger_hard

（分别对应为：连续出图、软触发和硬触发模式）

device_auto_reconnect

相机掉线重连

true/false

color_enable

彩色图像使能

true/false

color_resolution

彩色图像分辨率

设定范围请参考相机的 fetch_config.xml 文件

color_qos

Color 服务质量

SYSTEM_DEFAULT/DEFAULT/PARAMETER_EVENTS/SERVICES_DEFAULT/PARAMETERS/SENSOR_DATA

color_camera_info_qos

Color camera info 服务质量

SYSTEM_DEFAULT/DEFAULT/PARAMETER_EVENTS/SERVICES_DEFAULT/PARAMETERS/SENSOR_DATA

depth_enable

深度图像使能

true/false

depth_resolution

深度图像分辨率

设定范围请参考相机的 fetch_config.xml 文件

depth_qos

Depth 服务质量

SYSTEM_DEFAULT/DEFAULT/PARAMETER_EVENTS/SERVICES_DEFAULT/PARAMETERS/SENSOR_DATA

depth_camera_info_qos

Depth camera info 服务质量

SYSTEM_DEFAULT/DEFAULT/PARAMETER_EVENTS/SERVICES_DEFAULT/PARAMETERS/SENSOR_DATA

depth_registration_enable

Depth to Color 对齐使能

true/false

depth_speckle_filter

深度图斑点滤波器开关

true/false

max_speckle_size

斑点滤波器面积阈值

默认值：150，取值范围：10-3000

max_speckle_diff

斑点滤波器聚类

默认值：64，取值范围：5-1500

max_physical_size

最大物理尺寸

默认值：20.0

depth_time_domain_filter

时域滤波开关

true/false

depth_time_domain_num

时域滤波数量

默认值：3，范围：2-10

point_cloud_enable

点云图像使能

true/false

color_point_cloud_enable

彩色点云图像使能

true/false

point_cloud_qos

点云图服务质量

SYSTEM_DEFAULT/DEFAULT/PARAMETER_EVENTS/SERVICES_DEFAULT/PARAMETERS/SENSOR_DATA

ir_enhancement

红外增强方式

off/linear/multi_linear/std_linear/log/hist

ir_enhancement_coefficient

红外增强系数

默认值：9；multi_linear：1-20； std_linear：3-10； log：10-30

ir_undistortion

红外畸变矫正

true/false

left_ir_enable

左 IR 图像使能

true/false

left_ir_qos

左 IR 服务质量

SYSTEM_DEFAULT/DEFAULT/PARAMETER_EVENTS/SERVICES_DEFAULT/PARAMETERS/SENSOR_DATA

left_ir_camera_info_qos

左 IR camera info 服务质量

SYSTEM_DEFAULT/DEFAULT/PARAMETER_EVENTS/SERVICES_DEFAULT/PARAMETERS/SENSOR_DATA

注解

xxx_qos 可配值说明：

SYSTEM_DEFAULT：使用系统的默认 QoS 设置，这些设置通常由底层的 DDS（Data Distribution Service）实现定义。效果取决于具体的 DDS 实现。

DEFAULT：提供可靠的消息传递，适用于大多数通用的通信需求。最多保留 10 条最新消息。

PARAMETER_EVENTS：专门用于参数事件的 QoS 设置，确保参数变化事件能够可靠传递。最多保留 1000 条最新消息。

SERVICES_DEFAULT：服务通信的默认 QoS 设置，确保服务请求和响应能够可靠传递。保留所有服务请求和响应消息。

PARAMETERS：专门用于参数的 QoS 设置，确保参数设置和获取的可靠性。最多保留 1000 条最新消息。

SENSOR_DATA：传感器数据的 QoS 设置，适用于高频率、低延迟的数据流传输。最多保留 5 条最新消息。

当通过 percipio.launch 文件配置了相机不支持的图像分辨率时，相机将输出默认配置的图像。

方法三：编辑 parameters.xml 配置文件

进入 “camport_ros2/install/percipio_camera/share/percipio_camera/launch” 中配置相机节点启动时加载的参数。该方法仅适用于设置文件中包含的参数。

参数设置说明如下：

1.Float型参数

<feature name="DepthScaleUnit">0.125</feature> //0.125对应的地方写目标参数值

2.Int型参数

<feature name="DepthSgbmImageNumber">1</feature> //1对应的地方写目标参数值

3.Bool型参数

<feature name="ExposureAuto">1</feature> //1对应的地方写值，注意此处写1或0，不能写true或false

4.Enum型参数

<feature name="DepthStreamTofChannel">0</feature> //0对应的地方写枚举值对应的整型值

启动相机节点

ros2 launch percipio_camera percipio_camera.launch.py

ros2 launch percipio_camera multi_cam.launch.py

若相机节点正常启动，终端会打印相机 IP、SN、深度图及彩色图格式与分辨率等信息。

注意

运行过程中，请勿关闭该服务终端。

订阅主题

可订阅的主题

/camera/color/camera_info
/camera/color/image_raw
/camera/depth/camera_info
/camera/depth/image_raw
/camera/depth_registration/points
/camera/depth/points
/camera/left_ir/image_raw
/camera/device_event
/camera/dynamic_config
/camera/reset
/camera/soft_trigger
/parameter_events
/rosout
/tf_static

注解

启用 color_point_cloud_enable 时，point_cloud_enable 将被自动置为 false。因此 /camera/depth_registered/points 和 /camera/depth/points 不会同时存在。

预览图像

“install/percipio_camera/share/percipio_camera/launch” 路径包含 Python 示例程序，如查看深度图、彩色图、点云图、彩色点云图。

depth.py：使能指定相机采集指定图像格式和分辨率的深度图像。

a. 在 percipio.launch 文件中，将 depth_enable 置为 true 并保存。

b. 打开终端1，启动相机节点。

c. 打开终端2，切换到 “install/percipio_camera/share/percipio_camera/launch” 路径下，输入 python3 depth.py 并运行。

弹出的窗口将实时显示指定相机的深度图像。
color.py：使能指定相机采集到指定图像格式和分辨率的彩色图像。

a. 在 percipio.launch 文件中，将 color_enable 置为 true 并保存。

b. 打开终端1，启动相机节点。

c. 打开终端2，切换到 “install/percipio_camera/share/percipio_camera/launch” 路径下，输入 python3 color.py 并运行。

弹出的窗口将实时显示指定相机的彩色图像。
cloud.py：使能指定相机采集到指定图像格式和分辨率的点云并保存。

a. 在 percipio.launch 文件中，将 depth_enable 与 point_cloud_enable 置为 true，并将 color_point_cloud_enable 置为 false。

b. 打开终端1，启动相机节点。

c. 打开终端2，切换到 “install/percipio_camera/share/percipio_camera/launch” 路径下，输入 python3 cloud.py 并运行。

弹出的窗口将实时显示指定相机的原始点云。同时，终端2将打印点云保存路径与点云点数。
registered_cloud.py：使能指定相机采集指定图像格式和分辨率的彩色点云并保存。

a. 在 percipio.launch 文件中，将 color_enable、depth_enable、depth_registration_enbale 与 color_point_cloud_enable 均置为 true 并保存，

b. 打开终端1，启动相机节点。

c. 打开终端2，切换到 “install/percipio_camera/share/percipio_camera/launch” 路径下，运行 python3 registered_cloud.py。

弹出的窗口将实时显示指定相机的彩色点云。同时，终端2将打印点云保存路径与点云点数。

相机软复位

当相机运行报错的时候，不方便对相机断电重启操作，可以使用相机软复位功能。

方式1：启动相机节点后，另开一个终端，切换到 “install/percipio_camera/share/percipio_camera/launch” 路径下。输入 python3 reset.py 并运行。

方式2：通过主题发送软重启命令。

ros2 topic pub /camera/reset std_msgs/msg/Empty "{}" -1

监听相机事件

可监听相机事件，如掉线、相机上线等功能。

方式1：启动相机节点后，另开一个终端，切换到 “install/percipio_camera/share/percipio_camera/launch” 路径下。输入 python3 offline_detect.py 并运行。

方式2：通过订阅主题进行监听。

ros2 topic echo /camera/device_event

动态修改相机参数

方式1：启动相机节点。切换到 “install/percipio_camera/share/percipio_camera/launch” 路径下，在 dynamic_config.py 文件中修改参数。另开一个终端，输入 python3 dynamic_config.py 并运行。

dynamic_config.py 文件

方式2：启动相机节点时动态修改相机参数。

ros2 run percipio_camera percipio_camera_node --ros-args -p serial_number:='"207000160264"' -p depth_enable:=true -p camera_parameter:='<source name="Left"><feature name="ExposureTime">5000</feature></source>'

方式3：通过订阅主题动态修改相机参数。

a. 启动相机节点

ros2 run percipio_camera percipio_camera_node --ros-args -p serial_number:='"207000160264"' -p depth_enable:=true

b. 另开终端并发送命令

ros2 topic pub /dynamic_config std_msgs/msg/String     "data: '<source name=\"Left\"><feature name=\"ExposureTime\">300</feature></source>'" -1

发送相机软触发

方式1：使用 send_trigger.py 用于发送软触发信号，相机收到信号后采集图像。

a. 打开 percipio_camera.launch.py 文件并设置 trigger_mode 参数为 true。

b. 打开终端1，启动相机节点。

c. 打开终端2，切换到 “install/percipio_camera/share/percipio_camera/launch” 路径下，输入 python3 send_trigger.py camera 10 并运行，给相机发送 10 条软触发指令。

d. 返回终端1，将显示已收到 10 条软触发指令。

方式2：通过命令发送软触发信号

a. 通过命令设置相机工作模式为 trigger_mode。

ros2 run percipio_camera percipio_camera_node --ros-args -p serial_number:='"207000160264"' -p device_workmode:="trigger_soft" -p color_enable:=true

b. 另起终端，发送触发信号

ros2 topic pub -r 1 /soft_trigger std_msgs/msg/String "data: 'trigger'"

辅助工具说明

list_devices 枚举相机

运行以下代码，可枚举与电脑连接的图漾相机。

ros2 run percipio_camera list_devices

network_ip_config 设置相机 IP 地址

运行以下代码，并按照提示操作，可完成相机 IP 地址设置。支持设置静态 IP 地址和动态 IP 地址。

ros2 run percipio_camera network_ip_config