• Stars
    star
    207
  • Rank 189,769 (Top 4 %)
  • Language
    C++
  • License
    Other
  • Created almost 3 years ago
  • Updated about 2 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Semantic LIDAR odometry and mapping for cylinderical objects (e.g. trees in forests)

Semantic Lidar Odometry and Mapping in Forests (SLOAM)

drawing

(Note: Trees in grey color do not represent all trees in the semantic map. Instead, they represent a submap centered around the robot that is used for data association.)


Setup a worskpace

Even though we recommend using docker to run SLOAM, we decided to keep the ROS workspace on the host machine and create a volume that maps the folder to the container. This way, we can discard the container once the execution stops, but also keep a cached version of the last compilation. To do this, we will need a worskpace with the following structure on your host machine:

sloam_ws/
  -> src/
      -> sloam (folder from this repo)
      -> sloam_msgs (folder from this repo)
      -> models (you have to create this)

Segmentation

You will also need a neural network model for tree segmentation. You can find the ones we used for pine trees here (we used the same model in real world and simulated experiments). Download the model and put it in the models folder.

We used RangeNet++ for segmentation. The trained model needs to be exported to ONNX format. Depending on your inputs/architecture you may need to change the file sloam/src/segmentation/inference.cpp. You may also need to change the seg_model_path in the file sloam/params/sloam.yaml to point to the trained model.

Docker Image

To build the Docker image locally, you can use the docker/build_sloam_image.sh script. This will create an image named sloam/runtime. WARNING we use multi-stage build to make sure the runtime image is as small as possible, but rebuilding the image will create an auxiliary image that is 26GB+.

Alternatively, you can download the built image from Docker hub

docker pull gnardari/sloam:runtime

Running the container

Now that you configured the workspace, it is time to configure the run script sloam/docker/run_sloam_container.sh.

You will have to change the variable in the first line of the file to where you created the workspace on your host machine and map a folder where you will put ROS bag files that will be accessed by the container:

# Example
SLOAMWS="$HOME/ros/sloam_ws"
BAGS_DIR="$HOME/bags"

Also check if the image name in the docker run command matches the image you built/downloaded.

Once inside the container, you can use TMUX to create many terminal windows with tmux.

Make sure that the Docker volume mapping the host workspace to the container is working by running cd /opt/sloam_ws/ && ls src. This directory should not be empty.

Local Installation

Instead of Docker, you can install all dependencies locally to run SLOAM. Please refer to the local installation README for instructions.

Build workspace

 cd /path/to/sloam_ws/
 catkin build -DCMAKE_BUILD_TYPE=Release

Starting the SLOAM Node

The launch file sloam/launch/sloam.launch contains the SLOAM parameters that you can tune. You can start SLOAM using the run.launch file for real world data (you may need to configure some parameters depending on your sensor) or use run_sim.launch to run SLOAM with simulated data. You can download an example bag here.

tmux
source devel/setup.bash
roslaunch sloam run_sim.launch # running sloam with sim data
ctrl+b % # create new TMUX pannel
cd ../bags/
rosbag play example.bag # play bag

Odometry Backbone

This version of SLOAM requires an odometry backbone to receive an initial guess for pose estimation. The bags we provided will have odometry messages, but for custom data, you will need to run another state estimation algorithm that will be used as an initial guess. Check out LLOL for a lidar odometry backbone and MSCKF for a stereo VIO option.

Parameter Tuning

Most of the SLOAM parameters can be viewed in the sloam/launch/sloam.launch file. There are also the run.launch and run_sim.launch files where you should define the lidar point cloud and odometry topics, but can be used to change other parameters specifically for your scenario.

Development

Code Structure

Here is a high level diagram of the code structure.

drawing

  • Input Manager will listen for Odometry and Point Cloud data and call SLOAM once the odometry estimated that the robot moved minOdomDistance from the previous keyframe.
  • SLOAM Node is the central piece that will call other parts of the code and publish the outputs.
  • Inference will run the neural network and create two new point clouds with points labeled as trees and another with points labeled as background.
  • Trellis Graph uses the tree point cloud to detect individual trees.
  • SLOAM will receive individual tree detections, the submap of landmarks, the background cloud, plus the initial guess from the odometry. It will filter ground points using heuristics, estimate the semantic objects, perform data association, and pose estimation.
  • The results are added to the semantic map and published by the SLOAM Node.

Adding new dependencies to the image

The idea here is that container should be disposable. That means that changes made to the container will not be saved. Intead, you should change SLOAMDockerfile to install/change things in the image and rebuild it. Usually my development workflow is to run the commands inside the current version of the container to make sure it will work then add them to the build file.

Building the image

The script build_sloam_image.sh will take care of building everything. This file performs a two-stage build, where first we compile the C++ packages SLOAM depends on, and then we copy the built libraries to the runtime image. The BaseDockerfile will contain dependencies and configurations shared between the two stages.

./build_sloam_image.sh

Debugging

I recommed VSCode as your editor since it has some nice features to interface with Docker containers and ROS. If you do use it, install the plugin vscode-ros (just search for ROS on the plugin tab), Docker and Remote-Containers to access files and debug your code while running ROS nodes inside a Docker container.

Example debug config:

{
  "version": "0.2.0",
  "configurations": [{
      "name": "Node SLOAM",
      "request": "launch",
      "target": "/opt/sloam_ws/src/sloam/sloam/launch/run_sim.launch",
      "type": "ros"
  }]
}

In VSCode there will be an option on the left menu called Remote Explorer. Click it and choose your container. This will open a new VSCode window with acess to the files inside the container (including the ones that are being mapped from your local computer using a volume). If you don't have a debug launch file yet, open the launch file you are going to run and then go to the Debug tab also on the left menu. There will be an option create json config file. Once it is created, you can start debugging by running this file from the GUI.

Don't forget to compile with the cmake debug flag if that last compilation wasn't with this flag:

 catkin build -DCMAKE_BUILD_TYPE=Debug

Citing our work

@inproceedings{chen2019,
title={SLOAM: Semantic lidar odometry and mapping for forest inventory},
author={Chen, Steven W and Nardari, Guilherme V and Lee, Elijah S and Qu, Chao and Liu, Xu and Romero, Roseli Ap Francelin and Kumar, Vijay},
booktitle={IEEE Robotics and Automation Letters (RA-L)},
year={2020}
}
@inproceedings{liu2022large,
title={Large-scale Autonomous Flight with Real-time Semantic SLAM under Dense Forest Canopy},
author={Liu, Xu and Nardari, Guilherme V and Ojeda, Fernando Cladera and Tao, Yuezhan and Zhou, Alex and Donnelly, Thomas and Qu, Chao and Chen, Steven W and Romero, Roseli AF and Taylor, Camillo J and others},
journal={IEEE Robotics and Automation Letters (RA-L)},
year={2022}
}

More Repositories

1

msckf_vio

Robust Stereo Visual Inertial Odometry for Fast Autonomous Flight
C++
1,722
star
2

kr_autonomous_flight

KR (KumarRobotics) autonomous flight system for GPS-denied quadrotors
C++
671
star
3

ublox

A driver for ublox gps
C++
446
star
4

jps3d

A C++ implementation of Jump Point Search on both 2D and 3D maps
C++
373
star
5

multicam_calibration

C++
118
star
6

conformal_lattice_planner

C++
116
star
7

kr_mav_control

Code for quadrotor control
C++
106
star
8

sdd_vio

Semi-Dense Direct Visual-Inertial Odometry
C++
97
star
9

mrsl_quadrotor

C++
93
star
10

motion_capture_system

Drivers for motion capture systems (Vicon and Qualisys, can be extended to compatible with other mocap systems)
C++
66
star
11

AllocNet

A lightweight learning-based trajectory optimization framework.
C++
58
star
12

bluefox2

ROS driver for the Matrix Vision mvBlueFOX cameras
C++
46
star
13

imu_vn_100

ROS driver for VN-100 of VectorNav Technologies
C
46
star
14

velodyne_puck

A simplified driver for Velodyne VLP16 (PUCK) based on the official ROS velodyne driver.
C++
37
star
15

gps-tools

ROS packages for use with GPS
C++
36
star
16

waypoint_navigation_plugin

C++
36
star
17

treescope

Python
35
star
18

spomp-system

CMake
35
star
19

kr_mp_design

A guidance for the design and evaluation of motion planners for quadrotors in Environments with Varying Complexities
35
star
20

imu_3dm_gx4

Driver for Lord Corporation Microstrain 3DM GX4 25
C++
32
star
21

flir_gige

A ros driver for flir ax5 gige thermal camera
C++
28
star
22

vicon

Code for working with the Vicon tracking system
C++
24
star
23

flea3

ROS driver for flea3/grasshopper3 camera
C++
21
star
24

MOCHA

Multi-robot Opportunistic Communication Framework for Heterogeneous Collaboration
Python
21
star
25

ouster_decoder

A low latency decoder for Ouster Lidars
C++
17
star
26

camera_base

Some base classes for simplifing ROS camera driver node.
C++
13
star
27

kr_param_map

A parameterized map generator for planning evaluations and benchmarking
C++
13
star
28

CoverageControl

Environment for coverage control and learning using GNN
C++
12
star
29

imu_3dm_gx3

Driver for Lord Corporation Microstrain 3DM GX3 25
C++
10
star
30

kr_ilqr_optimizer

Use iLQR package Altro to fly the quadrotor
C++
9
star
31

kr_opt_sfc

Optimal Convex Cover to Approximate Collision-free Space
9
star
32

asoom

C++
8
star
33

nanokontrol

C++
7
star
34

top_down_renderer

C++
5
star
35

grid_map

C++
4
star
36

spomp

C++
4
star
37

multi_mav_manager

This is a multi MAV manager which leverages mav_manager and quadrotor_control for each agent.
Shell
3
star
38

air_router

Python
3
star
39

video_magics

Shell
3
star
40

kr_utils

Collection of utils packages
C++
2
star
41

kr_docs

Repository for documentation relevant to the KumarRobotics organization
2
star
42

ublox-release

Release repo for ublox driver (ros1)
2
star
43

rangenet_inf

Python
1
star
44

kr_planning_msgs

C++
1
star
45

quadrotor_ukf

Quadrotor UKF
C++
1
star
46

kr_param_yaw

A Trajectory Optimization Method with Global Yaw Parameterization
1
star
47

semantics_manager

Python
1
star
48

starling2_interface

Starling 2 Integration
CMake
1
star