NeuPan ROS2笔记

标准文档入口neupan_ros2/src/neupan_ros2/README_cn.md at main · KevinLADLee/neupan_ros2
根目录md是旧版的

快速上手

安装，拉取的是一整个ROS2工作空间

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
git clone https://github.com/KevinLADLee/neupan_ros2.git
cd neupan_ros2

# 安装系统依赖
chmod +x setup.sh
./setup.sh

# 配置依赖
uv venv
uv pip install torch torchvision "numpy<2.0" --torch-backend=auto

# 拉取Neupan的主仓库
git clone https://github.com/hanruihua/NeuPAN.git
uv pip install -e NeuPAN/

# 构建工作空间
chmod +x build.sh
./build.sh

# Source 工作空间
source install/setup.bash

自定义模型

需要从配置模版创建配置文件
配置教程在neupan_ros2/src/neupan_ros2/config/robots/README.md
快速从模板复制出来，模板在工作空间/src/neupan_ros2/config/robots/__template

1
2
3
4
cd ./src/neupan_ros2/config/robots
cp -r _template my_robot
mv robot.yaml.template robot.yaml
mv planner.yaml.template planner.yaml

编辑 robot.yaml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
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
    scan_angle_min: -3.14
    scan_downsample: 1
    scan_range_max: 5.0
    scan_range_min: 0.01
    flip_angle: false
    refresh_initial_path: true
    include_initial_path_direction: false
    control_frequency: 50.0  # Control loop frequency (Hz)

    # ========== 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'

编辑 planner.yaml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
# 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

开始训练：NeuPan 笔记

快速开始

1
2
3
git clone https://github.com/hanruihua/NeuPAN
uv venv
uv pip install -e NeuPAN

在NeuPAN本体的NeuPAN/example/dune_train
/dune_train_diff.yaml，修改这个文件，这个是四驱差速小车的配置文件
添加device: 'cuda'就可以使用GPU加速，然后修改小车实际的长和宽，再编辑雷达的范围就好了

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
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

run起来

1
uv run NeuPAN/example/dune_train/dune_train_diff.py

如果报错提示 ModuleNotFoundError: No module named 'tkinter' ，说明系统缺少 tkinter 包，运行 sudo apt install python3-tk安装后再运行训练指令即可。
训练完测后，输出模型保存位置：

1
2
3
4
save model at epoch 5000
Training... ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00
finish train, the model is saved in NeuPAN/example/dune_train/model/diff_robot_default/model_5000.pth
Complete Training. The model is saved in NeuPAN/example/dune_train/model/diff_robot_default/model_5000.pth

复制到NeuPAN_ROS2

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

启动！！！

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

1
cp limo.launch.py my_robot.launch.py

然后修改一下

1
2
3
4
5
# 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')

回到工作空间中，重新构建

1
colcon build --symlink-install --packages-select neupan_ros2

然后就是正式启动

1
ros2 launch neupan_ros2 my_robot.launch.py

解释

DUNE (Distance-Underlying Neural Encoder) —— “几何直觉”

  • 是什么： 一个特殊的神经网络（深度展开网络），负责处理激光雷达的点云数据。
  • 做什么： 传统算法通常把障碍物简化成圆形或方框，导致精度丢失。DUNE 不做简化，它直接计算原始点云与机器人真实物理形状之间的“隐式距离特征”（Latent Distance Features）。
  • 特点： 它不是黑盒网络，而是由数学优化算法（PIBCD）展开而成的，因此具有可解释性。它能告诉控制器：“虽然看着很窄，但根据我的几何形状，这里还有 3cm 的空隙，可以过”。

NRMP (Neural Regularized Motion Planner) —— “运动理性”

  • 是什么： 一个基于优化的运动规划器（类似于 MPC）。
  • 做什么： 它接收 DUNE 传来的距离特征，将其作为“惩罚项”（Regularizer）放入数学公式中求解。它计算出的速度和转向角必须严格符合机器人的物理限制（如最大速度、转弯半径）。
  • 特点： 它是“可微”的，这意味着如果机器人撞车了，系统可以通过反向传播自动调整参数，自我学习如何避障。