图漾相机-ROS2-SDK-Ubuntu 4.X.X版本编译

前言

   官网ROS2 4.X.X版本编译文档链接：
   https://doc.percipio.xyz/cam/latest/apiguides/sdk4.0-ros2-compile.html
  国内gitee下载SDK链接：
  https://gitee.com/percipioxyz/camport_ros2
  国外github下载SDK链接：
  https://github.com/percipioxyz/camport_ros2

1.PercipioViewer软件调试相机参数

  新版本的PercipioViewer2.6.1支持把调试好的参数，保存进相机Storage区，具体操作如下：
  图漾相机保存参数配置

1.1 PV软件保存相机参数

  1.打开目标相机
  2.根据实际情况调整相机属性，以达到最佳效果。
  3.在设置完相机参数后，关闭所有相机取流。
  4.点击菜单栏 Tools > Parameters，进入 Camera parameters configuration 页面

保存参数设置

  注1：此界面只有PercipioViewer 2.6.1以上 版本才有，同时在进行保存参数前，需要关闭相机各个组件取流。
  注2：当前保存相机参数至相机storage的方式，只能保存各个组件下的Controls下的属性功能，一些图像后处理方式，暂未保存至相机storage区内。

1.2 保存参数注意事项

  1.在打开相机取流的时候，无法进行参数保存，需要关闭相机取流后，再进行保存参数。
  2.无法保存相机Device组件里的触发属性,。

  3.无法保存深度图和点云图的质量评估及后处理功能。

  4.无法保存Color组件的校正畸变，以及AutoISP功能。

  5.相机系统层的属性无法保存，如对时设置，接收包比例，图像重传等功能。

1.3 FS/PM带SGBM参数相机调参说明

  诸如FM855-E1，FM815-IX-E1，PS800，PS802等带有SGBM参数的相机，需要进行如下操作，才能打开SGBM参数:

  相机参数说明连接
  而SGBM参数主要作用如下：

1.3.1 disparityNum和disparityOffset参数调整技巧

  disparityNum：视差范围。
  disparityOffset：最小视差值。

使用场景：
   客户想要更改预定义的深度范围（近远端值）。
调整方向:
   深度范围减小， disparityNum大概率减小。
   深度范围远端往相机端缩进， disparityOffset变大，反之亦反。

   而disparityNum和disparityOffset参数设置，计算公式如下：

disparityNum = (baseline* fx) / depth_thres.first - (baseline* fx) / depth_thres.second + 15;
disparityOffset = ((baseline * fx) / (depth_thres.second)) - DISPARITY_TRANSLATION;

  计算公式里的每个参数的具体含义如下：

  完整的计算表格从本帖子置顶位置下载。

1.3.2 matchWinW和matchWinH参数调整技巧

  matchWinW：匹配块横向大小
  matchWinH：匹配块纵向大小

使用场景：
  针对被测物要测量的特征（针对的是平滑面，还是物体细节），进行细微的调整。
调整方向：
  一般的预设置的匹配块大小可认为是一个全局考虑的值；深度图越需要平滑的，匹配块大概率是从预设值向大调整，反之，亦反。

注意事项：请首先按照 matchWinW = matchWinH 的方式进行调整；
一般匹配块大小必须是奇数且大于等于3；

1.3.3 P1和P2参数调整技巧

  P1：控制视差平滑度的第一个参数。
  P1_scale：控制视差平滑度的尺度参数。
  P2：控制视差平滑度的第二个参数。

使用场景： 需要调整深度图平滑度的情况。
调整方向 P1越大，越倾向于生成连续的视差图。 P1scale作用在平滑度上，P1sacle范围是[0~1]，越大就越平滑。 P2越大，越倾向于消除小的视差变化。P2必须大于P1。

  注意事项：建议先调整P1sacle，后P1，再P2。

1.3.4 uniqueFator和uniqueAbsDiff参数调整技巧

  uniqueFator：唯一性检查阈值，最优与次优的比值约束。
  uniqueAbsDiff：唯一性检查阈值，绝对值差阈值。

使用场景：被测物有杂点、飞点、空洞过多等情况。
调整方向：后处理约束参数调整过小会产生杂点或飞点；过大则会产生大片空洞。 一般uniqueAbsDiff 比 uniqueFator约束性更强。

1.4 推荐使用相机

  推荐原因如下：

2.新版PercipioViewer软件

   图漾新的PMD和GM46X相机，需要使用新版本软件，支持相机参数保存，同时断电生效。

2.1 软件使用

   待补充

3. 4.X.X版本 Camport ROS2 SDK

  4.X.X SDK版本与3.X.X版本基本一致，详细编译过程可参考如下链接：
   4.X.X版本SDK编译流程

3.1 4.X.X版本 Camport ROS2 SDK源文件介绍

  Camport ROS2 SDK 的目录，目录包含了camport4，include，launch，src。

1.README.md：
  简述了 ROS2 编译过程。
2.src/percipio_camera/CMakeLists.txt：
  Cmake 编译系统的规则文件。
3.src/percipio_camera/camport4：
  这个目录包含了Percipio SDK的库文件和头文件。SDK 提供了与相机硬件交互的底层接口，用于初始化相机、获取图像和点云数据等。
4.src/percipio_camera/include：
  这个目录包含了头文件，定义了接口和数据结构。
  这些头文件通常用于声明相机驱动的类和函数。
5.src/percipio_camera/launch：
  这个目录包含了ROS2的启动文件，用于启动节点和配置参数。
   启动文件可以配置相机参数，并启动必要的节点。

该目录还包含以下python文件：

   1.cam_base_cfg.launch.py:
   2.cloud.py：
   3.color.py：
   4.depth.py：
   5.multi_cam.launch.py：
   6.offline_detect.py:
   7.percipio_camera.launch.py:
   8.registered_cloud.py：
   9.send_trigger.py：

6.src/percipio_camera/package.xml：
  描述功能包清单的文件，包括功能包的名称、版本号、作者信息、许可信息、编译依赖等。
7.src/percipio_camera/src：
   包含主要的源代码文件，包括节点实现、相机驱动等。

3.2 4.X.X版本 Camport ROS2 SDK工作流程

3.2.1 包含头文件

  包含必要的ROS2头文件，例如rclcpp。

3.2 2 初始化 ROS2 节点

  使用 rclcpp::init(argc, argv); 初始化ROS2。

3.2.3 创建节点对象

  使用 rclcpp::Node::make_shared(“节点名称”) ，创建节点对象。

3.2.4 创建发布者对象并实现发布逻辑

  使用 node->create_publisher<消息类型>(“话题名称”, 队列大小);
创建发布者对象。实现发布逻辑，例如在回调函数中发布消息。

3.2.5 启动ROS2

  使用 ros2 run 包名 节点名 运行指定的 ROS 2 节点。
  使用 ros2 launch 包名 launch文件名 启动包含多个节点的 launch 文件。

3.3 4.X.X版本 ROS2 SDK环境配置与编译

  主要针对ubuntu20.04对应ROS2 Foxy，以及ubuntu22.04对应ROS2 Humble两个版本的系统进行操作。

3.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

第五步:camport4_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：包含编译和运行时生成的日志文件。

3.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。这意味着构建将进行优化，适合发布版本，而不是调试版本。

3.3.3 编译文件检查

  编译后会生成build，install，log。

1.build：

  包含了编译过程中生成的中间文件和目标文件。
  包括对象文件(.o）、依赖文件等。 该目录在每次编译时都会被更新。

2.install：

   这个目录包含了安装后的文件。
  包括可执行文件、库文件、头文件和其他资源文件，用于运行时使用，包含了所有需要的文件和依赖项。

3.log：

  这个目录包含了编译和运行时生成的日志文件。
   包括编译日志、运行时日志和错误日志等，这些日志文件对于调试和诊断问题非常有用。

4.4.X.X版本 参数配置

4.1 方法一修改相机launch文件

  1.在launch文件(percipio_camera.launch.py / multi_cam.launch.py )中配置相机启动时加载的参数。
  2.该方法仅适用于设置 launch文件中包含的参数，具体步骤如下：进入“camport_ros2/install/percipio_camera/share/percipio_camera/launch” 路径。
  3.如需配置相机的所有参数，可选择使用PercipioViewer提前将相机参数配置写入Storage，后续打开相机后参数便是配置好的状态。设置步骤请参见参数配置管理

4.1.1 单相机

  如使用单台相机，打开percipio_camera.launch.py 文件，并根据需要修改参数配置，可配参数的说明见下表。
  指定相机SN号：

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

  指定相机IP地址：

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

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

4.1.2 多相机

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

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

4.1.3 launch文件参数说明

launch文件属性说明

4.2 通过看图软件修改参数

  1.GigE2.0相机(除 PMD系列与GM 系列以外的相机）

  通过 Percipio Viewer 或 Camport SDK 3.X.X 将参数保存至相机 Storage 区，ROS启动时将自动加载storage 区的参数配置并开始采集图像。
  2.GigE2.1 相机(PMD 系列与 GM 系列相机)
  通过Camport SDK 4.X.X或新版PercipioViewer设置相机默认加载目标 User Set 属性组，相机上电后将自动加载该User Set属性组的参数配置。

5.4.X.X版本 Camport ROS2常见问题汇总

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

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

5.2 相机实际输出的图像格式或分辨率为什么未按照用户预设参数(userset)或存储区(storage)的配置？

  答：如相机存储区或者 userset 中设置了图像的格式和分辨率，且percipio.launch 文件也配置了图像的分辨率和格式，那么，ROS2优先通过launch文件中配置的参数。

6.补充资料

  1.Cmake菜谱