Baike.dev
All toolsOnline toolsAI codingTrendingOpen sourceNewsSubmit
Log in
< Back to tools
P

PX4-Avoidance

> 编程语言
Open source

PX4 avoidance ROS node for obstacle detection and avoidance.

748 stars0 likes1 views
WebsiteGitHub

About

PX4 avoidance ROS node for obstacle detection and avoidance.

Obstacle Detection and Avoidance

Warning: This project is currently not maintained.

We'd welcome community support to maintain and update the project. If you're interested in contributing, please contact the PX4 development team through normal channels. PX4 computer vision algorithms packaged as ROS nodes for depth sensor fusion and obstacle avoidance. This repository contains three different implementations:

  • local_planner is a local VFH+* based planner that plans (including some history) in a vector field histogram
  • global_planner is a global, graph based planner that plans in a traditional octomap occupancy grid
  • safe_landing_planner is a local planner to find safe area to land

The three algorithms are standalone and they are not meant to be used together.

The local_planner requires less computational power but it doesn't compute optimal paths towards the goal since it doesn't store information about the already explored environment. An in-depth discussion on how it works can be found in this thesis. On the other hand, the global_planner is computationally more expensive since it builds a map of the environment. For the map to be good enough for navigation, accurate global position and heading are required. An in-depth discussion on how it works can be found in this thesis. The safe_landing_planner classifies the terrain underneath the vehicle based on the mean and standard deviation of the z coordinate of pointcloud points. The pointcloud from a downwards facing sensor is binned into a 2D grid based on the xy point coordinates. For each bin, the mean and standard deviation of z coordinate of the points are calculated and they are used to locate flat areas where it is safe to land.

Note The most developed and used planner is the local_planner. This is where you should start.

The documentation contains information about how to setup and run the two planner systems on the Gazebo simulator and on a companion computer running Ubuntu 20.04 (recommended), for both avoidance and collision prevention use cases.

Note PX4-side setup is covered in the PX4 User Guide:

  • Obstacle Avoidance
  • Collision Prevention

Table of Contents

  • Getting Started
    • Installation
      • Installation for Ubuntu
    • Run the Avoidance Gazebo Simulation
      • Local Planner
      • Global Planner
      • Safe Landing Planner
    • Run on Hardware
      • Prerequisite
      • Local Planner
      • Global Planner
  • Troubleshooting
  • Advanced
    • Message Flows
      • PX4 and local planner
      • PX4 and global planner
  • Contributing

Getting Started

Installation

Installation

This is a step-by-step guide to install and build all the prerequisites for running the avoidance module on Ubuntu 20.04 with ROS Noetic (includes Gazebo 11). You might want to skip some steps if your system is already partially installed.

Note: These instructions assume your catkin workspace (in which we will build the avoidance module) is in ~/catkin_ws, and the PX4 Firmware directory is ~/Firmware. Feel free to adapt this to your situation.

  1. Add ROS to sources.list:

    bash
    sudo sh -c 'echo "deb http://packages.ros.org/ros/ubuntu $(lsb_release -sc) main" > /etc/apt/sources.list.d/ros-latest.list'
sudo apt install curl
curl -s https://raw.githubusercontent.com/ros/rosdistro/master/ros.asc | sudo apt-key add -
sudo apt update

  2. Install ROS with Gazebo:

    bash
    sudo apt install ros-noetic-desktop-full

# Source ROS
echo "source /opt/ros/noetic/setup.bash" >> ~/.bashrc
source ~/.bashrc

    Note We recommend you use the version of Gazebo that comes with your (full) installation of ROS. If you must to use another Gazebo version, remember to install associated ros-gazebo related packages:

    • For Gazebo 8,
      bash
      sudo apt install ros-noetic-gazebo8-*
    • For Gazebo 9,
      bash
      sudo apt install ros-noetic-gazebo9-*

  3. Dependencies for building packages

    bash
    sudo apt install python3-rosdep python3-rosinstall python3-rosinstall-generator python3-wstool build-essential

  4. Install and initialize rosdep.

    bash
    rosdep init
rosdep update

  5. Install catkin and create your catkin workspace directory.

    bash
    sudo apt install python3-catkin-tools
mkdir -p ~/catkin_ws/src

  6. Install MAVROS (version 0.29.0 or above).

    Note: Instructions to install MAVROS from sources can be found here.

    bash
    sudo apt install ros-noetic-mavros ros-noetic-mavros-extras

  7. Install the geographiclib dataset

    bash
    wget https://raw.githubusercontent.com/mavlink/mavros/master/mavros/scripts/install_geographiclib_datasets.sh
chmod +x install_geographiclib_datasets.sh
sudo ./install_geographiclib_datasets.sh

  8. Install avoidance module dependencies (pointcloud library and octomap).

    bash
    sudo apt install libpcl1 ros-noetic-octomap-*

  9. Clone this repository in your catkin workspace in order to build the avoidance node.

    bash
    cd ~/catkin_ws/src
git clone https://github.com/PX4/avoidance.git

  10. Actually build the avoidance node.

    bash
    catkin build -w ~/catkin_ws

    Note that you can build the node in release mode this way:

    bash
    catkin build -w ~/catkin_ws --cmake-args -DCMAKE_BUILD_TYPE=Release

  11. Source the catkin setup.bash from your catkin workspace:

    bash
    echo "source ~/catkin_ws/devel/setup.bash" >> ~/.bashrc
source ~/.bashrc

Run the Avoidance Gazebo Simulation

In the following section we guide you through installing and running a Gazebo simulation of both local and global planner.

Build and Run the Simulator

  1. Clone the PX4 Firmware and all its submodules (it may take some time).

    bash
    cd ~
git clone https://github.com/PX4/Firmware.git --recursive
cd ~/Firmware

  2. Install PX4 dependencies.

    bash
    # Install PX4 "common" dependencies.
./Tools/setup/ubuntu.sh --no-sim-tools --no-nuttx

# Gstreamer plugins (for Gazebo camera)
sudo apt install gstreamer1.0-plugins-bad gstreamer1.0-plugins-base gstreamer1.0-plugins-good gstreamer1.0-plugins-ugly libgstreamer-plugins-base1.0-dev

  3. Build the Firmware once in order to generate SDF model files for Gazebo. This step will actually run a simulation (that you can immediately close).

    bash
    # This is necessary to prevent some Qt-related errors (feel free to try to omit it)
export QT_X11_NO_MITSHM=1

# Build and run simulation
make px4_sitl_default gazebo

# Quit the simulation (Ctrl+C)

# Setup some more Gazebo-related environment variables (modify this line based on the location of the Firmware folder on your machine)
. ~/Firmware/Tools/simulation/gazebo-classic/setup_gazebo.bash ~/Firmware ~/Firmware/build/px4_sitl_default

  4. Add the Firmware directory to ROS_PACKAGE_PATH so that ROS can start PX4:

    bash
    export ROS_PACKAGE_PATH=${ROS_PACKAGE_PATH}:~/Firmware

  5. Finally, set the GAZEBO_MODEL_PATH in your bashrc:

    bash
    echo "export GAZEBO_MODEL_PATH=${GAZEBO_MODEL_PATH}:~/catkin_ws/src/avoidance/avoidance/sim/models:~/catkin_ws/src/avoidance/avoidance/sim/worlds" >> ~/.bashrc

The last three steps, together with sourcing your catkin setup.bash (source ~/catkin_ws/devel/setup.bash) should be repeated each time a new terminal window is open.

OR you can ensure your ~/.bashrc is setup correctly so that each new terminal is sourced correctly.

bash
sudo nano ~/.bashrc

Ensure that at the bottom of that document you have exactly this:

bash
source /opt/ros/noetic/setup.bash
source ~/catkin_ws/devel/setup.bash
. ~/Firmware/Tools/simulation/gazebo-classic/setup_gazebo.bash ~/Firmware ~/Firmware/build/px4_sitl_default
export GAZEBO_MODEL_PATH=${GAZEBO_MODEL_PATH}:~/catkin_ws/src/avoidance/avoidance/sim/models:~/catkin_ws/src/avoidance/avoidance/sim/worlds
export ROS_PACKAGE_PATH=${ROS_PACKAGE_PATH}:~/Firmware

You should now be ready to run the simulation using local or global planner.

Local Planner (default, heavily flight tested)

This section shows how to start the local_planner and use it for avoidance in mission or offboard mode.

The planner is based on the 3DVFH+ algorithm.

Note: You may need to install some additional dependencies to run the following code (if not installed):

bash
sudo apt install ros-noetic-stereo-image-proc ros-noetic-image-view

Any of the following three launch file scripts can be used to run local planner:

Note: The scripts run the same planner but simulate different sensor/camera setups. They all enable Obstacle Avoidance and Collision Prevention.

  • local_planner_stereo: simulates a vehicle with a stereo camera that uses OpenCV's block matching algorithm (SGBM by default) to generate depth information

    bash
    roslaunch local_planner local_planner_stereo.launch

    Note: The disparity map from stereo-image-proc is published as a stereo_msgs/DisparityImage message, which is not supported by rviz or rqt. To visualize the message, first open a new terminal and setup the required environment variables:

    bash
    source devel/setup.bash

    Then do either of:

    • run:
      bash
      rosrun image_view stereo_view stereo:=/stereo image:=image_rect_color
    • publish the DisparityImage as a simple sensor_msgs/Image:
      bash
      rosrun topic_tools transform /stereo/disparity /stereo/disparity_image sensor_msgs/Image 'm.image'

    The disparity map can then be visualized by rviz or rqt under the topic /stereo/disparity_image.

  • local_planner_depth_camera: simulates vehicle with one forward-facing kinect sensor

    bash
    roslaunch local_planner local_planner_depth-camera.launch

  • local_planner_sitl_3cam: simulates vehicle with 3 kinect sensors (left, right, front)

    bash
    roslaunch local_planner local_planner_sitl_3cam.launch

You will see the Iris drone unarmed in the Gazebo world. To start flying, there are two options: OFFBOARD or MISSION mode. For OFFBOARD, run:

bash
# In another terminal 
rosrun mavros mavsys mode -c OFFBOARD
rosrun mavros mavsafety arm

…

bash
roslaunch global_planner global_planner_stereo.launch

You should now see the drone unarmed on the ground in a forest environment as pictured below.

To start flying, put the drone in OFFBOARD mode and arm it. The avoidance node will then take control of it.

bash
# In another terminal
rosrun mavros mavsys mode -c OFFBOARD
rosrun mavros mavsafety arm

Initially the drone should just hover at 3.5m altitude.

From the command line, you can also make Gazebo follow the drone, if you want.

bash
gz camera --camera-name=gzclient_camera --follow=iris

…

bash
roslaunch safe_landing_planner safe_lan

Issues· 0 open

View all issuesOpen on GitHub

No open issues yet, or sync has not completed.

> Tags

C++

No comments yet. Be the first to share.

> Details

PublishedAug 1, 2026
UpdatedSep 17, 2026
Category编程语言
PricingOpen source

> Related tools

T
TypeScript
JavaScript 的超集，为前端与全栈提供静态类型
P
Python
通用编程语言，广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言