Ubuntu22.04 + ROS2 Humble 安装部署 PCT Planner

一、项目介绍

基于PCT Planner 的多楼层3D全局路径规划技术创新性地解决了多楼层3D导航的难题，整个工作流程主要分为环境预处理 和路径规划两部分。

1. 整体工作流概览

规划的核心思想，是利用点云生成一系列2D"断层扫描图像（Tomogram）"作为多楼层导航的基础地图。整个工作流程可以分为线下和线上两个阶段：

线下预处理 (Tomography) ：输入原始3D点云地图，通过GPU加速的断层扫描算法，生成一张2.5D的可通行性代价地图（Tomogram） ，格式为.pickle文件。
线上规划 (Planning)：在RViz2中交互式选择起点和终点，规划器会在这张预处理好的地图上进行A*搜索，得到一条平滑的3D路径，并实时避开悬空障碍物。

2. 可通行区域判断：从3D点云到2.5D代价图

判断"哪里能走"的本质，是通过层析技术将复杂的3D空间降维成易于计算的2.5D地图，具体包含以下核心步骤：

生成层析切片 (Tomogram Slices) ：算法沿Z轴以固定分辨率扫描点云，在每个垂直区间内，计算出局部地面高度 和天花板高度，将包含楼板、斜坡等不同高度的物理结构编码为多个2D切片。
评估机器人运动能力：在每个切片上，算法会综合考量机器人的尺寸和通过性，计算出每个位置的可通行性代价值。

可通行性代价值（intensity）：

物理尺寸 ：确保有足够的最小垂直净空 （如0.50米）和碰撞安全半径 （如0.40米）。

台阶与坡度 ：评估机器人能否跨过最大台阶高度 （step_max，如0.17米）或爬上最大坡度 （slope_max，如23°）的区域。

安全性边际 ：除了硬性的障碍物，还会设置渐变的成本区域（inflation），让路径规划更自然地与障碍物保持距离。

3. 上下楼路径规划：在层析切片间无缝探索

这是PCT Planner的关键创新之一。它通过以下方式实现了上下楼的连续规划：

跨越切片的通用搜索 ：规划器将不同楼层的层析切片视为一个统一的图（Graph）进行搜索，搜索逻辑在物理上天然支持跨楼层。
以3D点连接不同楼层：楼梯或坡道在3D点云中表现为连续的斜面。算法在每个高度切片上检测到这些过渡区域，并通过搜索算法将其平滑地连接起来，从而在生成的最终3D路径中，自动包含从起点楼层到终点楼层的完整上下楼轨迹。

二、部署指南

1. 环境准备

安装ROS2 Humble、CUDA 12.x以及cmake、gcc、eigen3等系统工具。

（1）硬件与软件环境

建议先确认以下基础条件：

操作系统：Ubuntu 22.04 LTS
ROS2 发行版：Humble Hawksbill（桌面完整版）
CUDA ：11.5（系统预装，通过 nvidia-smi 确认驱动支持的 CUDA 版本）
Python：3.10

（2）检查 CUDA 和驱动

打开终端，输入：

bash 复制代码

nvidia-smi

查看驱动最高支持的CUDA版本：

打开终端，输入：

bash 复制代码

nvcc --version

查看实际安装的 CUDA Toolkit 版本：

注意：如果 nvcc 显示 CUDA 11.x，则必须安装 cupy-cuda11x；若显示 CUDA 12.x，则使用 cupy-cuda12x。

2. 获取源码并安装系统依赖

（1）创建工作空间并克隆仓库

打开终端，输入：

bash 复制代码

mkdir -p ~/d7lros2/PCT_ws

bash 复制代码

cd ~/d7lros2/PCT_ws

克隆仓库：

bash 复制代码

git clone https://github.com/rvxfahim/PCT_planner.git

bash 复制代码

cd PCT_planner

（2）安装依赖

更新源：

bash 复制代码

sudo apt update

安装依赖：

bash 复制代码

sudo apt install -y libeigen3-dev libboost-all-dev cmake build-essential

（3）设置 Python 虚拟环境

为避免依赖冲突，使用 Python 虚拟环境。

创建虚拟环境：

bash 复制代码

python3 -m venv ~/pct_venv

激活虚拟环境：

bash 复制代码

source ~/pct_venv/bin/activate

注意： ****每次使用前都需要重新激活虚拟环境。

升级 pip：

bash 复制代码

pip install --upgrade pip

（4）安装 Python 依赖

安装基础依赖：

bash 复制代码

pip install numpy==1.24.3
pip install scipy==1.10.1
pip install open3d==0.17.0
pip install scikit-learn==1.2.2

（5）安装 CuPy

根据 nvcc --version 显示的 CUDA 版本选择：

如果是CUDA 11.x，输入：

bash 复制代码

pip install cupy-cuda11x==13.6.0

如果是CUDA 12.x，输入：

bash 复制代码

pip install cupy-cuda12x==13.6.0

验证安装：

bash 复制代码

python3 -c "import cupy as cp; print(f'CuPy version: {cp.__version__}'); print(f'CUDA available: {cp.cuda.is_available()}')"

3. 编译 C++ 依赖库（GTSAM + OSQP）

打开终端，输入：

bash 复制代码

cd ~/d7lros2/PCT_ws/PCT_planner/planner

编译第三方库（约 5--10 分钟）：

bash 复制代码

bash build_thirdparty.sh

编译 pybind11 模块：

bash 复制代码

bash build.sh

编译完成后，会在 planner/lib/ 目录下生成 .so 文件。

三、测试验证

1. 准备点云数据

（1）使用示例点云（Building 场景）

打开终端，输入：

bash 复制代码

cd ~/d7lros2/PCT_ws/PCT_planner

解压缩点云文件：

bash 复制代码

unzip rsc/pcd/pcd_files.zip -d rsc/pcd/

（2）使用自定义点云（可选）

将自定义的 .pcd 文件复制到 rsc/pcd/，例如：

bash 复制代码

cp /path/to/your_cloud.pcd rsc/pcd/clinic.pcd

2. 生成断层扫描地图（Tomogram）

（1）为 Building 场景生成

打开终端，输入：

bash 复制代码

cd ~/d7lros2/PCT_ws/PCT_planner/tomography/scripts

激活环境：

bash 复制代码

source ~/pct_venv/bin/activate

场景生成：

bash 复制代码

python3 run_standalone.py --scene Building

成功输出示例：

bash 复制代码

[INFO] Loading PCD: .../building2_9.pcd
[INFO] PCD points: 853227
[INFO] Map center: [-0.37, 1.37]
[INFO] Dim_x: 285, Dim_y: 150
[INFO] Num slices init: 30 → simplified: 8
[INFO] Tomogram exported: .../rsc/tomogram/building2_9.pickle

（2）为自定义场景（如 clinic）生成

需先在 tomography/config/ 下创建 scene_clinic.py 配置文件（可参考 scene_building.py），然后运行：

bash 复制代码

python3 run_standalone.py --scene Clinic

3. 运行路径规划（无 ROS 测试，可选）

先验证整个流程是否正常，不依赖 ROS。打开终端，输入：

bash 复制代码

cd ~/d7lros2/PCT_ws/PCT_planner/planner/scripts

激活环境：

bash 复制代码

source ~/pct_venv/bin/activate

运行路径规划：

bash 复制代码

python3 plan_standalone.py --scene Building

如果成功，会输出路径规划信息和保存的轨迹文件。

4. 启动 ROS2 交互式规划

（1）准备符号链接（使节点能找到点云和 tomogram）

节点默认寻找 rsc/pcd/clinic.pcd 和 rsc/tomogram/clinic.pickle。我们可以用 Building 的数据建立链接：

bash 复制代码

cd ~/d7lros2/PCT_ws/PCT_planner

bash 复制代码

ln -sf rsc/pcd/building2_9.pcd rsc/pcd/clinic.pcd
ln -sf rsc/tomogram/building2_9.pickle rsc/tomogram/clinic.pickle

（2）启动 RViz2 可视化

打开一个终端，激活虚拟环境并 source ROS2：

bash 复制代码

source ~/pct_venv/bin/activate
source /opt/ros/humble/setup.bash

到你的工作目录：

bash 复制代码

cd ~/d7lros2/PCT_ws/PCT_planner

启动RVIZ：

bash 复制代码

rviz2 -d rsc/rviz/pct_ros2.rviz

（3）启动 ROS2 规划节点

打开另一个终端，激活虚拟环境并 source ROS2：

bash 复制代码

source ~/pct_venv/bin/activate
source /opt/ros/humble/setup.bash

到你的工作目录：

bash 复制代码

cd ~/d7lros2/PCT_ws/PCT_planner

运行路径规划：

bash 复制代码

python3 run_ros2_interactive.py --skip-tomo

参数 --skip-tomo 表示使用已有的 tomogram 文件，不再重新生成。

5. 在 RViz2 中交互式规划

（1）设置 Fixed Frame

在 RViz 左侧 Global Options 中，设置 Fixed Frame 为 map：

（2）显示点云和 tomogram

在 Displays 面板中，确保 Raw Point Cloud 和 Tomogram 都已勾选。

对于每个 PointCloud2 显示项，设置：

Style : Points 或 Squares
Size : 0.05 ~ 0.1
Color Transformer : Intensity（tomogram）或 AxisColor（调试）

6. 选择起点和终点

（1）切换为Orbit

左下角选择Orbit：

可以发现右边不再是俯视图：

（2）选择起点

点击工具栏的 Publish Point 按钮：

在点云地图上单击设置起点（绿色球体出现）：

（3）选择终点

在另一处单击设置终点（红色球体出现）：

规划器自动运行，成功后显示绿色路径线（/pct_path）。

（一）常见问题及解决方法汇总

问题现象原因解决方案

ModuleNotFoundError: No module named 'cupy' 未安装 CuPy 根据 nvcc --version 安装对应版本 cupy-cuda11x 或 cupy-cuda12x

ImportError: numpy.core.multiarray failed to import NumPy 版本与 CuPy 不兼容固定 NumPy 版本 pip install numpy==1.24.3

OSError: libnvrtc.so.12: cannot open shared object file CuPy 版本与系统 CUDA 不匹配系统 CUDA 11.5 却安装了 cupy-cuda12x，改用 cupy-cuda11x

ValueError: zero-size array 在 ROS2 节点启动时找不到 .pcd 文件创建符号链接指向存在的点云，或检查路径

RViz 中显示 Showing [0] points Frame_id 不匹配或 QoS 问题将 Global Options 的 Fixed Frame 设置为 map 或清空；重启节点

RViz 中看不到任何点云视图未对准将 Views 类型改为 Orbit，点击 Reset，然后缩放/旋转找到点云

Tomography 运行后生成的文件名不是 clinic.pickle 脚本默认使用场景名创建符号链接或修改 run_ros2_interactive.py 中的文件名

（二）参数调优参考

如需调整机器人尺寸、步高、坡度等，修改 tomography/config/scene_clinic.py 中的参数，然后重新生成 tomogram。详细说明见项目中的 PARAMETERS.md。

关键参数示例：

map.resolution：栅格分辨率（默认 0.10 m）

trav.safe_margin：碰撞半径（默认 0.4 m）

trav.step_max：最大可跨越台阶高度（默认 0.17 m）

trav.slope_max：最大可爬坡度（默认 0.40 rad ≈ 23°）

（三）完整部署检查清单

Ubuntu 22.04 + ROS2 Humble

NVIDIA 驱动正常，nvidia-smi 运行无误

nvcc 显示 CUDA 版本（11.x 或 12.x）

克隆仓库并安装系统依赖

创建 Python 虚拟环境并激活

安装 NumPy 1.24.3、SciPy、Open3D、scikit-learn

安装与 CUDA 版本匹配的 CuPy

编译 GTSAM 和 OSQP（build_thirdparty.sh）

编译 pybind11 模块（build.sh）

解压示例点云或准备自定义点云

生成 tomogram（run_standalone.py --scene Building）

测试无 ROS 规划（plan_standalone.py）

创建符号链接使 ROS2 节点能加载数据

启动 ROS2 节点（run_ros2_interactive.py --skip-tomo）

启动 RViz2，调整 Fixed Frame 和视图

在 RViz 中点击起点和终点，成功生成路径

问题现象	原因	解决方案
`ModuleNotFoundError: No module named 'cupy'`	未安装 CuPy	根据 `nvcc --version` 安装对应版本 `cupy-cuda11x` 或 `cupy-cuda12x`
`ImportError: numpy.core.multiarray failed to import`	NumPy 版本与 CuPy 不兼容	固定 NumPy 版本 `pip install numpy==1.24.3`
`OSError: libnvrtc.so.12: cannot open shared object file`	CuPy 版本与系统 CUDA 不匹配	系统 CUDA 11.5 却安装了 `cupy-cuda12x`，改用 `cupy-cuda11x`
`ValueError: zero-size array` 在 ROS2 节点启动时	找不到 `.pcd` 文件	创建符号链接指向存在的点云，或检查路径
RViz 中显示 `Showing [0] points`	Frame_id 不匹配或 QoS 问题	将 Global Options 的 Fixed Frame 设置为 `map` 或清空；重启节点
RViz 中看不到任何点云	视图未对准	将 Views 类型改为 `Orbit`，点击 Reset，然后缩放/旋转找到点云
Tomography 运行后生成的文件名不是 `clinic.pickle`	脚本默认使用场景名	创建符号链接或修改 `run_ros2_interactive.py` 中的文件名

Ubuntu22.04 + ROS2 Humble 安装部署 PCT Planner

一、项目介绍

1. 整体工作流概览

2. 可通行区域判断：从3D点云到2.5D代价图

可通行性代价值（intensity）：

3. 上下楼路径规划：在层析切片间无缝探索

二、部署指南

1. 环境准备

（1）硬件与软件环境

（2）检查 CUDA 和驱动

2. 获取源码并安装系统依赖

（1）创建工作空间并克隆仓库

（2）安装依赖

（3）设置 Python 虚拟环境

（4）安装 Python 依赖

（5）安装 CuPy

3. 编译 C++ 依赖库（GTSAM + OSQP）

三、测试验证

1. 准备点云数据

（1）使用示例点云（Building 场景）

（2）使用自定义点云（可选）

2. 生成断层扫描地图（Tomogram）

（1）为 Building 场景生成

（2）为自定义场景（如 clinic）生成

3. 运行路径规划（无 ROS 测试，可选）

4. 启动 ROS2 交互式规划

（1）准备符号链接（使节点能找到点云和 tomogram）

（2）启动 RViz2 可视化

（3）启动 ROS2 规划节点

5. 在 RViz2 中交互式规划

（1）设置 Fixed Frame

（2）显示点云和 tomogram

6. 选择起点和终点

（1）切换为Orbit

（2）选择起点

（3）选择终点

（一）常见问题及解决方法汇总

（二）参数调优参考

（三）完整部署检查清单

可通行性代价值（`intensity`）：