ROS 1 平台

ROS（Robot Operating System，下文简称 ROS）是一个适用于机器人的开源的元操作系统。它提供了操作系统应有的服务，包括硬件抽象，底层设备控制，常用函数的实现，进程间消息传递，以及包管理。

搭建 ROS 1 开发环境

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

  • Ubuntu16.04：ROS Kinetic

  • Ubuntu18.04：ROS Melodic

  • Ubuntu20.04：ROS Noetic

下载 Camport ROS 1 SDK

ROS 1 SDK 支持 ROS Kinetic、ROS Melodic 和 ROS Noetic 平台。

选择以下任意方式，下载 Camport ROS 1 SDK：

  • 使用浏览器下载： https://gitee.com/percipioxyz/camport_ros.git。

  • 使用 git 指令获取本地副本：打开终端，切换到需存放 SDK 的工作目录下，输入 git clone 命令克隆远程仓库。

    git clone https://gitee.com/percipioxyz/camport_ros.git

Camport ROS 1 SDK 的 src 源码目录包含以下两个核心模块：

  1. percipio_camera： 相机驱动核心模块，包括源文件和配置文件。

    percipio_camera/
├── 📂 camport4/                   # Camport4 SDK
├── 📂 cfg/                        # 动态配置
├── 📂 include/                    # 头文件
├── 📂 ros/                        # ROS配置
├── 📂 src/                        # 源码
├── 📂 srv/                        # 服务定义
├── 📂 test/                       # 测试
├── 📄 .travis.yml                 # CI配置
├── 📄 CHANGELOG.rst              # 更新日志
├── 📄 CMakeLists.txt             # 构建配置
├── 📄 package.xml                # ROS包定义
├── 📄 percipio_nodelets.xml      # Nodelet配置
└── 📄 README.md                  # 说明文档

  2. percipio_launch：启动配置模块，包括 launch 包。

    该包通过 XML 配置文件实现 ROS 节点的启动与配置，支持定义节点名称、类型、参数等属性。同时，其 launch 文件支持服务节点的声明，便于订阅服务的功能集成。包内提供了 Python 示例程序，具体使用方法请参见 订阅主题。

    percipio_launch/
├── 📂 launch/                    # ROS启动配置文件目录
│   ├── 📂 includes/              # 通用包含文件
│   ├── 📄 percipio.launch       # 单相机启动配置
│   └── 📄 percipio_multi.launch # 多相机启动配置
├── 📄 CHANGELOG.rst             # 版本更新日志
├── 📄 cloud.py                  # 点云显示与保存脚本
├── 📄 CMakeLists.txt            # CMake构建配置
├── 📄 color.py                  # 彩色图像显示脚本
├── 📄 depth.py                  # 深度图像显示脚本
├── 📄 depthcloud.py             # 彩色点云显示与保存脚本
├── 📄 device_event_listen.py    # 相机事件监听脚本
├── 📄 dynamic_config.py         # 动态参数配置脚本
├── 📄 package.xml               # ROS包定义文件
├── 📄 parameters.xml            # 相机参数配置文件
├── 📄 reset.py                  # 相机软件复位脚本
└── 📄 soft_trigger.py           # 软触发控制脚本

编译

在开发包根目录下执行以下命令，进行编译：

catkin_make -DCMAKE_BUILD_TYPE=Release
catkin_make install

编译后会生成 build 文件夹（包含中间文件）和 devel 文件夹（包含最终文件：头文件、动/静态库、可执行文件）。

注解

若在 Ubuntu 16.04 上编译报错，请参见 Ubuntu 16.04 编译 ROS 1 SDK 失败。

配置环境变量

在开发包根目录下执行以下命令，配置环境变量：

echo "source <开发包存放路径>/camport_ros/devel/setup.bash" >> ~/.bashrc
source ~/.bashrc

修改相机参数

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

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

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

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

  • GigE2.0 相机（除 PMD 系列与 GM 系列以外的相机）

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

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

在 percipio.launch 文件中配置相机节点启动时加载的参数。该方法仅适用于设置文件中包含的参数。

具体步骤如下：

  1. 执行以下命令，打开 percipio.launch 文件：

cd src/percipio_launch/launch/
gedit percipio.launch

  1. 根据实际需求调整配置文件中的参数值。

    示例：指定相机

    在文件中找到 device_id 参数，修改其 default 值。

    <arg name="device_id" default="207000106930" />

    小技巧

    • device_id 默认值为 #1，表示默认打开找到的第一个相机。

    • default 设置为相机 SN 时，表示通过指定序列号打开相机。

    • default 设置为相机 IP 时，表示通过指定 IP 打开相机。

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

    percipio.launch 可配置参数表

    属性名

    描述

    取值范围

    device_id

    指定相机

    #1 / 相机 SN / 相机 IP

    device_reconnection

    相机重连开关

    true/false

    device_log_enable

    打开/关闭相机 Log

    true/false

    device_log_level

    设置相机 Log 等级

    VERBOSE/DEBUG/INFO/WARNING/ERROR

    device_log_server_port

    设置服务器端口

    默认值：9001

    frame_rate_control

    帧率控制开关

    true/false

    frame_rate

    设置出图帧率

    浮点型，默认值：5.0

    trigger_mode

    触发模式开关

    true/false

    frame_rate_control 与 trigger_mode 不能同时打开。

    如两个同时打开，frame_rate_control 生效，trigger_mode 不生效。

    rgb_resolution

    彩色分辨率

    彩色图像的长x宽

    depth_resolution

    深度分辨率

    深度图像的长x宽

    rgb_format

    彩色图像格式

    mono/bayer/bgr/yuv/jpeg

    bayer：包含 CSI_BAYER10GRBG、BAYER8GB、BAYER8BG、CSI BAYER12GBRG

    mono：包含 MONO10

    yuv：包含 YUYV、YCbCr

    depth_format

    深度图像格式

    depth16/xyz48

    depth_registration

    深度图和彩色图对齐开关

    true/false

    只有同时打开彩色图和深度图后，此项使能开关才会生效。

    对于没有 RGB 组件的相机此设置无效。

    color_undistortion

    彩色图畸变校正开关

    true/false

    ir_undistortion

    红外图畸变校正开关

    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

    ir_enhancement

    红外增强方式

    off/linear/multi_linear/std_linear/log/hist

    ir_enhancement_coefficient

    红外增强系数

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

    use_device_time

    控制时间戳来源。

    true/false

    • true 表示使用设备硬件时间

    • false 表示使用 ROS 主机系统时间。

    注解

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

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

进入 “src/percipio_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对应的地方写枚举值对应的整型值

启动相机节点

在开发包根目录下执行以下命令，启动相机节点：

roslaunch percipio_launch percipio.launch

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

注意

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

订阅主题

可用的主题

  • /camera/PercipioDeviceEvent

  • /camera/Pointcloud2

  • /camera/camera_nodelet_manager/bond

  • /camera/depth/camera_info

  • /camera/depth/image

  • /camera/dynamic_config

  • /camera/ir/camera_info

  • /camera/ir/image

  • /camera/percipio_camera/parameter_descriptions

  • /camera/percipio_camera/parameter_updates

  • /camera/reset

  • /camera/rgb/camera_info

  • /camera/rgb/image

  • /rosout

  • /rosout_agg

  • /tf_static

预览图像

“src/percipio_launch” 包含 Python 示例程序，如查看深度图、彩色图、点云图、彩色点云图。

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

    a. 打开终端1，运行 roslaunch percipio_launch percipio.launch 以启动相机节点。
    b. 打开终端2，切换到 “src/percipio_launch” 路径下。输入 python3 depth.py 并运行。
    弹出的窗口将实时显示指定相机的深度图像。
    depth.py 运行结果

    depth.py 运行结果

  • color.py：使能指定相机采集到指定图像格式和分辨率的彩色图像。

    a. 打开终端1，运行 roslaunch percipio_launch percipio.launch 以启动相机节点。
    b. 打开终端2，切换到 “src/percipio_launch” 路径下。输入 python3 color.py 并运行。
    弹出的窗口将实时显示指定相机的 color 图像。
    color.py 运行结果

    color.py 运行结果

  • cloud.py：使能指定相机采集到指定图像格式和分辨率的点云并保存。

    a. 打开终端1，运行 roslaunch percipio_launch percipio.launch 以启动相机节点。
    b. 打开终端2，切换到 “src/percipio_launch” 路径下。输入 python3 cloud.py 并运行。
    弹出的窗口将实时显示指定相机的原始点云。同时，终端2将打印点云保存路径与点云点数。
    cloud.py 运行结果

    cloud.py 运行结果

  • depthcloud.py：使能指定相机采集指定图像格式和分辨率的彩色点云并保存。

    a. 在 percipio.launch 文件中，将 depth_registration 置为 true 并保存。
    b. 打开终端1，运行 roslaunch percipio_launch percipio.launch 以启动相机节点。
    c. 打开终端2，切换到 “src/percipio_launch” 路径下。输入 python3 depthcloud.py 并运行。
    弹出的窗口将实时显示指定相机的彩色点云。同时，终端2将打印点云保存路径与点云点数。
    depthcloud.py 运行结果

    depthcloud.py 运行结果

监听相机事件

device_event_listen.py：用于监听相机事件，如掉线、相机上线等功能。

a. 打开终端1，运行 roslaunch percipio_launch percipio.launch 以启动相机节点。
b. 打开终端2，切换到 “src/percipio_launch” 路径下。运行 python3 device_event_listen.py。
终端2上会显示监听到的事件（如相机断电重启后，显示相机掉线和连接）。
device_event_listen.py 运行结果

device_event_listen.py 运行结果

动态修改相机参数

dynamic_config.py：相机在运行期间，可通过该脚本动态修改相机参数。

a. 打开终端1，运行 roslaunch percipio_launch percipio.launch 以启动相机节点。
b. 进入 “src/percipio_launch” 路径，在 dynamic_config.py 文件中修改参数。

注解

动态配置的参数，只能是在相机采集过程中可以修改的参数，如曝光时间、增益、模拟增益、激光亮度等。

c. 打开终端2，输入 python3 dynamic_config.py 并运行。
d. 运行 python3 color.py，查看参数调整后的效果。
device_event_listen.py 运行结果

dynamic_config.py 文件

device_event_listen.py 运行结果

dynamic_config.py 运行结果

相机软复位

reset.py：当相机运行报错的时候，不方便对相机断电重启操作，可以通过该脚本使相机复位。

a. 打开终端1，运行 roslaunch percipio_launch percipio.launch 以启动相机节点。
b. 打开终端2，切换到 “src/percipio_launch” 路径下。输入 python3 color.py 并运行，使能相机采集图像。
c. 打开终端3，切换到 “src/percipio_launch” 路径下，输入 python3 reset.py 并运行，使相机复位。
d. 返回终端2，观察输出信息。若相机成功复位并重新开始采集图像，则表示复位操作已完成。
reset.py 运行结果

reset.py 运行结果

reset.py 运行结果

color.py 运行结果（相机复位后重新采图）

发送软触发信号

soft_trigger.py：用于发送软触发信号，相机收到信号后采集图像。

a. 打开 percipio.launch 文件并设置 trigger_mode 参数为 true。
b. 打开终端1，运行 roslaunch percipio_launch percipio.launch 以启动相机节点。
c. 打开终端2，切换到 “src/percipio_launch” 路径下，输入 python3 soft_trigger.py camera 10 并运行，给相机发送 10 条软触发指令。
d. 返回终端1，将显示已收到 10 条软触发指令。
soft_trigger.py 运行结果

soft_trigger.py 运行结果

soft_trigger.py 运行结果

启动相机节点的终端（接收到软触发指令）

辅助工具说明

list_devices 枚举相机

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

rosrun percipio_camera list_devices

network_ip_config 设置相机 IP 地址

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

rosrun percipio_camera network_ip_config

多相机配置与启动

ROS 1 支持多相机同时工作，请按以下步骤配置并启动多相机系统：

  1. 进入 “/src/percipio_launch/launch” 路径，打开 percipio_multi.launch 文件并完成多相机配置。

percipio_multi.launch 文件

percipio_multi.launch 文件

  1. 打开终端并运行以下代码，启动相机节点。

    roslaunch percipio_launch percipio_multi.launch

    启动成功后，终端将显示这两台相机已被配置且打开。

启动相机节点

节点启动后的终端显示 （配置相机）

启动相机节点

节点启动后的终端显示 （打开相机）

  1. 订阅主题并采集图像。

常见问题

Ubuntu 16.04 编译 ROS 1 SDK 失败

问题描述

Ubuntu 16.04 编译 ROS 1 SDK 过程中出现以下报错。

报错信息

报错信息

解决方法

修改以下两个文件后，重新编译即可。

  • src/percipio_camera/CMakeLists.txt 添加 “set(CMAKE_CXX_STANDARD 11)” 。

    报错信息

    CMakeLists.txt

  • src/percipio_camera/src/DepthStreamProc.cpp 添加 “#include <cstdlib>” 。

    报错信息

    DepthStreamProc.cpp

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

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

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

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