ROS 2 平台

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

搭建 ROS 2 开发环境

1. 根据 Ubuntu 版本，安装对应的 ROS 2 开发平台。

   • Ubuntu 20.04：ROS 2 Foxy

   • Ubuntu 22.04：ROS 2 Humble

2. 安装依赖。

   ROS 2 FoxyROS 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
   

3. 设置环境变量

   ROS 2 FoxyROS 2 Humble

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

准备 USB 相机环境

如需使用 USB 相机，需完成 Linux 平台 USB 相机环境准备。

下载 Camport ROS 2 SDK

1. 创建工作目录

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

2. 下载 Camport ROS 2 SDK。

国内国外

选择以下任意方式，下载 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 的目录如下图所示：

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

修改参数配置

备注

如使用 USB 相机，请先完成 Linux 平台 USB 相机环境准备 步骤，再进行以下操作。

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

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

• GenICam 相机（PMD 系列与 GM 系列相机）

  通过 Viewer 软件 将参数设置保存至 UserSet 属性组，并将该组设置为默认加载的 User Set 属性组，相机上电后将自动加载该 User Set 属性组的参数配置。

• 非 GenICam 相机（除 PMD 系列与 GM 系列以外的相机）

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

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

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

1. 进入 “camport_ros2/install/percipio_camera/share/percipio_camera/launch” 路径。

2. 修改参数配置。

单相机多相机

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

示例：指定相机

• 指定相机 SN 号

  DeclareLaunchArgument('serial_number', default_value='"207000106930"'),
  

• 指定相机 IP 地址

  DeclareLaunchArgument('device_ip', default_value='192.168.120.112'),
  

备注

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

更多参数配置说明，请参见下表。

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

备注

1. 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 条最新消息。

2. 当通过 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

若相机节点正常启动，终端会打印相机 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

firmware_update 相机固件升级

运行以下命令，并根据提示选择是否保留用户数据。

ros2 run percipio_camera firmware_update {固件文件路径} -id {需要升级的设备 SN}

例如：

ros2 run percipio_camera firmware_update /home/k/21.bin -id 207000184055

运行后，可选择以下升级方式：

• 0：升级时保留用户数据

• 1：升级时不保留用户数据

常见问题

当系统中配置了 ROS 1 和 ROS 2，运行时报错

删除编译生成的文件后，临时隐藏 ROS1。

sudo mv /opt/ros/noetic /opt/ros/noetic.HIDDEN

noetic 根据系统自行修改，然后重新进行编译即可。

启用时域滤波后，运行 python3 depth.py 无法立即输出深度图

时域滤波功能需先采集 2-10 帧原始深度数据填充缓冲区（具体帧数可配置），经多帧时间域融合计算后才会输出深度图像，因此程序启动后会存在短暂延迟。

相机实际输出的图像格式或分辨率未按照 UserSet 用户预设参数或 Storage 存储区的配置

如相机存储区或者 UserSet 中设置了图像的格式和分辨率，且 percipio.launch 文件也配置了图像的分辨率和格式，那么，ROS 优先通过 launch 文件动态设置这些参数。

运行 cloud.py 报错

报错信息：No module named ‘open3d’

运行以下代码，安装open3d。

pip3.10 install open3d