TechROS2NeuPANPythonUbuntu
ROS2 Humble 基于 UV 配置 NeuPAN 实现无图导航
2026年2月7日
更新于 2026年2月12日
1,852 字
约 9 分钟

前言

本文涵盖从环境搭建、NeuPAN配置、仿真、实机部署全流程。

NeuPAN: Direct Point Robot Navigation with End-to-End Model-based LearningNavigating a nonholonomic robot in a cluttered, unknown environment requires accurate perception and precise motion control for real-time collision avoidance. This paper presents NeuPAN: a real-time, highly accurate, map-free, easy-to-deploy, and environment-invariant robot motion planner. Leveraging a tightly coupled perception-to-control framework, NeuPAN has two key innovations compared to existing approaches: 1) it directly maps raw point cloud data to a latent distance feature space for collision-free motion generation, avoiding error propagation from the perception to control pipeline; 2) it is interpretable from an end-to-end model-based learning perspective. The crux of NeuPAN is solving an end-to-end mathematical model with numerous point-level constraints using a plug-and-play (PnP) proximal alternating-minimization network (PAN), incorporating neurons in the loop. This allows NeuPAN to generate real-time, physically interpretable motions. It seamlessly integrates data and knowledge engines, and its network parameters can be fine-tuned via backpropagation. We evaluate NeuPAN on a ground mobile robot, a wheel-legged robot, and an autonomous vehicle, in extensive simulated and real-world environments. Results demonstrate that NeuPAN outperforms existing baselines in terms of accuracy, efficiency, robustness, and generalization capabilities across various environments, including the cluttered sandbox, office, corridor, and parking lot. We show that NeuPAN works well in unknown and unstructured environments with arbitrarily shaped objects, transforming impassable paths into passable ones.logohttps://arxiv.org/abs/2403.06828
main_image

不要阅读 https://github.com/KevinLADLee/neupan_ros2 仓库根目录下的 README.md，里面的教程作者不更新！应该阅读子目录下的 https://github.com/KevinLADLee/neupan_ros2/blob/main/src/neupan_ros2/README.md，坑爹！

复现环境

  1. Ubuntu 22.04
  2. ROS2 Humble
  3. UV

环境配置

克隆 NeuPAN ROS2 仓库

克隆 neupan ros_2 仓库 ，并进入。此处我们不需要历史提交记录，加上 --depth 1 加速克隆。

bash
git clone https://github.com/KevinLADLee/neupan_ros2 --depth 1
cd neupan_ros2
chmod +x *.sh

安装系统依赖

bash
./setup.sh

通过 UV 配置 Python 环境

在工作空间中初始化 python 虚拟环境并安装依赖。这里为了安装方便就不使用 pyproject 了

对于 neupan 而言使用 Python 3.10 最佳，同时注意 neupan 要求 numpy 版本 < 2.0

bash
uv venv
uv pip install torch torchvision "numpy<2.0" --torch-backend=auto

克隆 neupan 主仓库 ，并安装依赖项目

bash
git clone https://github.com/hanruihua/NeuPAN --depth 1
uv pip install -e NeuPAN/

编译 ROS2 工作空间

bash
./build.sh

仿真

编译成功后即可启用仿真，可以写入 sim.sh 快速启动

bash
# 配置环境
source .venv/bin/activate
export PYTHONPATH=$PYTHONPATH:$(pwd)/NeuPAN:$(pwd)/.venv/lib/python3.10/site-packages
source install/setup.bash
# 启动仿真
ros2 launch neupan_ros2 sim_complete.launch.py

注意，以下根目录README提供的代码是过时的😅，sim_diff_launch.py 早就被作者干掉了，更新的文档在 neupan_ros2/src/neupan_ros2 at main · KevinLADLee/neupan_ros2：

Launch files:

bash
source install/setup.bash
ros2 launch neupan_ros2 sim_diff_launch.py sim_env_config:=scenario_corridor.yaml

feat: Add robot-based configuration structure with Scout Mini and Ran… · KevinLADLee/neupan_ros2@da63060…ger Mini 3.0 support (#3) * refactor: migrate to robot-based configuration architecture Restructure configuration and launch files to support multiple robot platforms: Configuration: - Introduc…logohttps://github.com/kevinladlee/neupan_ros2/commit/da6306054f2015fb1ab73fd8309675ed4ba771fc
main_image

实机部署

创建机器人配置文件

从模板创建配置文件，这里以 my_robot 为例

配置教程可以在 /src/neupan_ros2/config/robots/_template/README.md 阅读，需要修改的字段我在下面的代码块里也用注释表起来了。

这些配置文件的详解可以参考官方仓库 https://github.com/hanruihua/NeuPAN/blob/579e7afa239cd7ff61f7f63fbd4aaaecbb136d3b/README.md

bash
cd ./src/neupan_ros2/config/robots
cp -r _template my_robot
mv robot.yaml.template robot.yaml
mv planner.yaml.template planner.yaml

编辑 planner.yaml ，我的底盘是四驱，所以选择差速模型。 最大速度和加速度根据自己机器人的性能调整，注意必须调整 length 和 width 描述机器人的长宽

💡 定义长宽时，应直接测量包括轮子的真实长宽，不需要额外冗余空间。不过误差在20%以内表现都不会差。
安全裕度在同配置文件的 adjust 处修改

yaml
# mpc
receding: 8
step_time: 0.25
ref_speed: 0.5
device: 'cpu'
time_print: False
collision_threshold: 0.01

# robot
robot:
  kinematics: 'diff'       # 4驱选择差速 'diff'，阿克曼选择 'acker'，两天前更新的 neupan 又加了一个 omni 给全向机器人
  max_speed: [0.5, 1.0]    # [线速度 m/s, 角速度 rad/s] -> 根据你机器人的实际能力修改
  max_acce: [0.5, 1.0]     # 最大加速度
  length: 0.6              # 【重要】测量你机器人的真实长度（米）
  width: 0.55              # 【重要】测量你机器人的真实宽度（米）
#  wheelbase:              # 仅阿克曼需要配置

# initial path
ipath:
  interval: 0.03
  # waypoints: [[0, 0, 0], [1, 0, 0]]
  curve_style: 'line'      # 四驱用 'line' 阿克曼用 'dubins' 或 reeds
  min_radius: 0.05         # 差速机器人可以原地转向，最小半径为 0# robot
  loop: False
  arrive_threshold: 0.5
  close_threshold: 0.05
  arrive_index_threshold: 3
  
# proximal alternating minimization network
pan:
  iter_num: 2
  dune_max_num: 200
  nrmp_max_num: 10
  dune_checkpoint: None
  iter_threshold: 0.1

# adjust parameters
adjust:
  q_s: 1.0
  p_u: 0.5
  eta: 15.0
  d_max: 0.1  # 最大安全裕度（米），过大会增加计算量
  d_min: 0.01 # 最小安全裕度（米），过小可能导致碰撞风险

编辑 robot.yaml

yaml
neupan_node:
  ros__parameters:
    # Robot identification
    robot_type: 'my_robot' # 修改成自己机器人的名字，对，名字
    robot_description: 'LIMO differential drive robot' # 机器人描述

    # Configuration file paths (relative to robot directory)
    planner_config_file: 'planner.yaml'
    dune_checkpoint_file: 'models/dune_model_5000.pth' # 我们后续训练的 DUNE 模型路径，如果大小和雷达性能和他的差不多，也可以先凑合着用，但是有碰撞风险。。。

    # TF Frame configuration
    map_frame: 'map'
    base_frame: 'livox_frame'
    lidar_frame: 'livox_frame'

    # Visualization control
    enable_visualization: true   # 总开关，关了就全关了
    enable_dune_markers: true    # DUNE 点云标记（关闭这个可以节约5-10% CPU损耗，嵌入式部署时推荐关闭，测试可以先留着）
    enable_nrmp_markers: true    # NRMP 点云标记
    enable_robot_marker: true    # 机器人足迹标记
    marker_size: 0.05
    marker_z: 1.0

    # Scan processing
    scan_angle_max: 3.14         # 激光雷达最大角度，如果不是360度会需要改这个
    scan_angle_min: -3.14        # 激光雷达最小角度，如果不是360度会需要改这个
    scan_downsample: 1
    scan_range_max: 30.0         # 激光雷达最大扫描距离（米）
    scan_range_min: 0.01         # 激光雷达最小扫描距离（米）
    flip_angle: false
    refresh_initial_path: true
    include_initial_path_direction: false
    control_frequency: 50.0      # 规划和控制循环的频率 (Hz)，推荐 10 - 100 以内

    # ========== Topic Configuration (Optional) ==========
    # Uncomment and modify to customize topic names for your robot
    # cmd_vel_topic: '/neupan_cmd_vel'
    # scan_topic: '/scan'
    # plan_input_topic: '/plan'
    # goal_topic: '/goal_pose'

训练 DUNE 模型

NeuPAN 最大的好处就在于我们只需要根据小车的尺寸和激光雷达的扫描范围的训练一个输出控制指令的端到端神经网络即可，无需依赖外部环境，因此可以训一个模型适应各类变化。

DUNE 模型的训练十分简单，仅需调用官方仓库的代码即可。但是训练对 CPU 和 GPU 性能要求都比较高（主要是CPU，因为 cvxpy 不支持GPU加速），推荐在自己的电脑上训练，服务器即便GPU强劲也会因为CPU拉跨导致训练时间反而更久。而边缘设备根据测试在 Jetson Orin Nano Super 上 CPU 训练需要大概 8 小时。

也可以使用我创建的 Colab Notebook 用 T4 在线训练，由于CPU较弱，大约需要 2 个小时。

Google ColabSign inlogohttps://colab.research.google.com/drive/1zel7_myxdj0t1lsvug2gzf5fsbwbiz-r
main_image

bash
git clone https://github.com/hanruihua/NeuPAN --depth 1
uv sync # 下载 Python 依赖
cd ./NeuPAN/example/dune_train/

编辑 dune_train_diff.yaml 配置文件（如果是阿克曼则编辑 dune_train_acker.yaml） 注意添加一行 device: 'cuda' 以启用 GPU 加速。 在 i5-12600KF+RTX4070TI 上使用 CUDA 训练大约使用 30 分钟。

yaml
device: 'cuda' # 重要：启用CUDA加速，不加这一行就是使用 CPU 训练
robot:
  kinematics: 'diff'
  length: 0.6  # 机器人的长，和之前配置文件一样
  width: 0.55   # 机器人的宽，和之前配置文件一样


train:
  direct_train: true
  data_size: 100000
  data_range: [-30, -30, 30, 30] # 激光雷达的半径构建的矩形，比如说半径 30m，就都写 30
  batch_size: 256
  epoch: 5000
  valid_freq: 250
  save_freq: 500
  lr: 5e-5
  lr_decay: 0.5
  decay_freq: 1500

开始训练

bash
uv run dune_train_diff.py

如果报错提示 ModuleNotFoundError: No module named 'tkinter' ，说明系统缺少 tkinter 包，运行 sudo apt install python3-tk安装后再运行训练指令即可。

训练完测后，输出模型保存位置

bash
Training... ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00
finish train, the model is saved in /data/neupan_ros2/NeuPAN/example/dune_train/model/diff_robot_default/model_5000.pth
Complete Training. The model is saved in /data/neupan_ros2/NeuPAN/example/dune_train/model/diff_robot_default/model_5000.pth

复制到配置文件夹的 models文件夹下，文件名要与 robot.yaml 中配置的完全一致

bash
cp /data/neupan_ros2/NeuPAN/example/dune_train/model/diff_robot_default/model_5000.pth /data/neupan_ros2/src/neupan_ros2/config/robots/my_robot/models/dune_model_5000.pth

至此模型训练完成。

配置启动脚本

回到 neupan_ros2/src/neupan_ros2/launch，根据自己的小车类型复制一份启动脚本。

bash
cp limo.launch.py my_robot.launch.py

编辑打开，修改其中对模型配置的引用路径

yaml
# Configuration paths
    pkg_share = get_package_share_directory('neupan_ros2')
    robot_config_dir = os.path.join(pkg_share, 'config', 'robots', 'my_robot') # 这里原 limo 改为自己的机器人文件夹名
    robot_config = os.path.join(robot_config_dir, 'robot.yaml')
    rviz_config = os.path.join(pkg_share, 'rviz', 'neupan_sim.rviz')

回到工作空间 neupan_ros2 目录，重新构建 neupan_ros2 包

bash
colcon build --packages-select neupan_ros2

部署

首先根据自己的机器人配置启动底盘，然后运行启动脚本即可

bash
ros2 launch neupan_ros2 my_robot.launch.py

Refs:

GitHub - hanruihua/NeuPAN: [TRO 2025] NeuPAN: Direct Point Robot Navigation with End-to-End Model-based Learning.[TRO 2025] NeuPAN: Direct Point Robot Navigation with End-to-End Model-based Learning. - hanruihua/NeuPANlogohttps://github.com/hanruihua/neupan
main_image

GitHub - KevinLADLee/neupan_ros2Contribute to KevinLADLee/neupan_ros2 development by creating an account on GitHub.logohttps://github.com/kevinladlee/neupan_ros2
main_image

Yachiyo~~