无人机避障项目——Fast-Planner——Terrestrial-Aerial-Navigation——运行环境配置

操作系统环境： ubuntu-20.04

项目地址：

https://github.com/HKUST-Aerial-Robotics/Fast-Planner

https://github.com/ZJU-FAST-Lab/Terrestrial-Aerial-Navigation

进入 Ubuntu 并安装基础工具

sudo apt update
sudo apt install -y build-essential cmake git curl \
  ca-certificates gnupg software-properties-common \
  pkg-config python3-dev python3-pip mesa-utils x11-apps

测试图形化界面是否成功：

xeyes -geometry 400x250+100+100

看到眼球随鼠标移动的窗口，表示基本图形界面正常。本次 xclock 的字体警告和窗口不可见，最终通过 xeyes 测试及重启 WSL 排查。

安装 ROS Noetic

执行位置：Ubuntu 20.04 终端。该项目使用 ROS 1 和 catkin；本次采用官方 ros-apt-source 配置包管理软件源和密钥，不再重复添加旧教程中的 ros1.list。

准备软件源工具

sudo apt update
sudo apt install -y curl ca-certificates software-properties-common
sudo add-apt-repository -y universe

安装官方软件源配置包

curl -fL --connect-timeout 20 --max-time 120 \
  https://github.com/ros-infrastructure/ros-apt-source/releases/download/1.3.0/ros-apt-source_1.3.0.focal_all.deb \
  -o /tmp/ros-apt-source.deb
sudo apt install -y /tmp/ros-apt-source.deb

此下载地址为本次流程使用的 1.3.0 focal 版本。若网络或地址发生变化，核对官方发布页；不要在下载失败后继续安装空文件，也不要关闭签名验证。

安装与加载 ROS

sudo apt update
sudo apt install -y ros-noetic-desktop
source /opt/ros/noetic/setup.bash
grep -qxF 'source /opt/ros/noetic/setup.bash' ~/.bashrc \
  || echo 'source /opt/ros/noetic/setup.bash' >> ~/.bashrc

验证

rosversion -d

rosversion -d 应输出 noetic。source 加载当前终端所需的命令和包路径；写入 .bashrc 后，新开的 Bash 会自动加载。

启动测试与停止维护提示

roscore

出现 started core service [/rosout] 等信息后，按 Ctrl+C 停止测试。ROS Noetic 于 2025年5月31日结束上游维护，这不等于已安装程序到期停用；本次模型显示问题不能由这个提示直接解释。

安装项目依赖

以下列表依据当前仓库依赖整理；已安装的软件包会由 apt 自动跳过。

sudo apt install -y \
  build-essential cmake git python3-dev \
  libeigen3-dev libarmadillo-dev \
  libopencv-dev libpcl-dev libboost-all-dev \
  libnlopt-dev libnlopt-cxx-dev qtbase5-dev \
  ros-noetic-cmake-modules ros-noetic-cv-bridge \
  ros-noetic-image-transport ros-noetic-pcl-ros \
  ros-noetic-pcl-conversions \
  ros-noetic-dynamic-reconfigure \
  ros-noetic-message-generation \
  ros-noetic-message-runtime ros-noetic-tf

可选操作：

以 https://github.com/ZJU-FAST-Lab/Terrestrial-Aerial-Navigation
项目为例：

修复 CMake 并配置 CPU 仿真
修复 Windows 检出后的顶层链接
本地 src/CMakeLists.txt 原本只有一行 /opt/ros/noetic/share/catkin/cmake/toplevel.cmake，属于链接被保存成普通文本的情况。先检查，再仅在需要时修复。
cd ~/projects/Terrestrial-Aerial-Navigation
ls -l src/CMakeLists.txt
cat src/CMakeLists.txt
若仍是上述单行普通文件，执行一次：
mv src/CMakeLists.txt src/CMakeLists.txt.windows-backup
ln -s /opt/ros/noetic/share/catkin/cmake/toplevel.cmake
src/CMakeLists.txt

关闭 CUDA 并切换点云输入

因为原始项目需要使用CUDA，也就是说需要使用nvidia显卡，但是很多时候我们的电脑硬件不满足这个条件，于是可以把项目的CUDA依赖关掉，只使用CPU。

下面脚本先检查两个文件，再修改并保存备份。关闭 CUDA 后，CPU 分支不发布原深度图，因此必须一起更改地图输入。

建立 x.py 文件，并将该文件放入到项目的根目录。

from pathlib import Path
import shutil
changes = [
 (Path('src/uav_simulator/local_sensing/CMakeLists.txt'),
  'set(ENABLE_CUDA true)', 'set(ENABLE_CUDA false)'),
 (Path('src/TIE_navigation/plan_manage/launch/kino_algorithm.xml'),
  'name="sdf_map/global_sensing"        value="false"',
  'name="sdf_map/global_sensing"        value="true"')]
for path, old, new in changes:
    text = path.read_text()
    assert old in text or new in text, str(path)
for path, old, new in changes:
    backup = Path(str(path) + '.before-cpu')
    if not backup.exists():
        shutil.copy2(path, backup)
    path.write_text(path.read_text().replace(old, new))
print('CPU 配置完成')

本方案读取全局点云用于首次部署验证。不要把该设置描述为已经复现未知环境的局部感知实验。

编译与判断编译状态

cd ~/projects/Terrestrial-Aerial-Navigation
source /opt/ros/noetic/setup.bash
set -o pipefail
catkin_make -j2 -l2 \
  -DCMAKE_BUILD_TYPE=Release \
  -DCATKIN_ENABLE_TESTING=ON \
  2>&1 | tee build.log

-j2 限制两个并行任务；-l2 设置负载限制；Release 使用优化构建；ON 避免 uav_utils 中无条件 catkin_add_gtest 与关闭测试配置冲突。tee 将输出同时显示并写入 build.log，pipefail 让流水线退出码能够反映构建失败。

如何确认完成与成功

原编译终端重新出现提示符表示命令结束。本次日志包含 [100%] Built target fast_planner_node，未见最终构建失败。若刚结束且未执行其他命令，可检查退出码；0 表示成功。

echo $?
tail -n 40 build.log

echo $? 只检查紧前一条命令。如果已执行其他命令，不要用它回溯构建结果。日志末尾再次出现 Running command 可能来自输出缓冲，不能单凭该行判断仍在编译。

启动仿真与 RViz 操作

加载工作空间并启动

cd ~/projects/Terrestrial-Aerial-Navigation
source /opt/ros/noetic/setup.bash
source devel/setup.bash
rospack find plan_manage
LIBGL_ALWAYS_SOFTWARE=true \
  roslaunch plan_manage kino_replan.launch

rospack 用于确认项目已加入包搜索路径。软件渲染变量仅对这次命令及其子进程生效，解决本机默认渲染路径下模型不可见的问题。roslaunch 会按启动文件组织节点，通常无需另开 roscore。

发送目标点

机器人初始位置约为 (-8, 0, 0)。先拉远视角看清地图，点击工具栏 2D Nav Goal，在机器人附近的空闲区域按住左键并拖动，松开发送目标。不要将目标直接放在障碍物内部或地图范围之外。
若出现轨迹且机器人位置随之变化，说明该目标下的规划与模拟执行链路可用。先验证短距离运动，再尝试障碍另一侧的目标。

关闭与保存

在仿真终端按 Ctrl+C 结束仿真。关闭额外手动启动的 RViz 窗口，并停止 STL 桥接脚本。需要保留显示设置时，在 RViz 中使用 File → Save Config As 保存到固定文件，不要长期依赖 /tmp 中的测试配置。

最后的效果图