Skip to content

Home

Jump to bottom
pdell-kitware edited this page Oct 9, 2021 · 5 revisions

Welcome to the pyLiDAR-SLAM wiki!

The documentation is organised as follows:

  • HOME Gives an overview of the project and how to utilize the configuration
  • INSTALLATION: Describes how to install pyLiDAR-SLAM and its different components
  • DATASETS: Describes the different datasets integrated in pyLiDAR-SLAM, and how to install them
  • TOOLBOX: Describes the contents of the toolbox and the different modules proposed
  • BENCHMARK: Describes the benchmarks supported in the Dataset /!\ Note: This section is still in construction
  • RESEARCH: Points to our research papers / work using pyLiDAR-SLAM

A More Detailed Overview

Project structure

├─ config                  # Configuration files schemas 
├─ slam 
    ├─ common              # Common components 
    ├─ dataset             # Code to load Datasets 
    ├─ eval                # Code to evaluate the quality of SLAM algorithms 
    ├─ models              # PoseNet model code 
    ├─ odometry            # Odometry modules 
    ├─ training            # Modules for training PoseNet models 
    ├─ initialization.py   # Modules for Initial motion estimate 
    ├─ preprocessing.py    # Modules for Preprocessing the point cloud 
    ├─ backend.py          # backend modules
    ├─ loop_closure.py     # loop closure modules
    └─ viz                 # Tools for visualization 

├─ tests
├─ run.py                  # Main script to run a LiDAR SLAM on sequences of a Dataset
└─ train.py                # Main script to launch a training

Understanding the configuration:

Using Hydra, one can easily change any element of the configuration by adding an argument to the launch script.

The configuration is organised into groups, within each group, multiple base configurations are defined by a simple string.

Selecting within a group a configurations is done as follows:

python run.py <config-path-to-group>/<group>=<config_name>

The configuration hierarchy in this project follows the hierarchy of folder config, consists of the following groups:

├─ config
    ├─ hydra                        # Hydra configuration files
    ├─ dataset                      # Dataset Group 
        ├─ kitti.yaml                   # KITTI default configuration
        ├─ nclt.yaml                    # NCLT default configuration
        └─ ford_campus.yaml             # FORD CAMPUS default configuration
    ├─ slam 
        ├─ odometry         
            ├─ alignment                # Alignment Group (will be expended in the future)
                └─ point_to_plane_GN.yaml   # Point-to-Plane alignment for the Frame-to-Model
            └─ local_map                # The Local Map Group
                ├─ projective               # The projective Frame-to-Model proposed
                └─ kdtree                   # The kdtree based Frame-to-Model alignmeeent 
        ├─ preprocessing            # Preprocessing Group
            ├─ grid_sample            
            ├─ voxelization            
               ...

        ├─ initialization           # Initialization Group
            ├─ CV.yaml                  # Configuration for the constant velocity model
            ├─ PoseNet.yaml             # Configuration for using PoseNet as initialization
            └─ EI.yaml                  # Elevation Image 2D registration configuration
            
        ├─ loop_closure                 # Loop Closure Group
        └─ backend                      # Backend Group

    ├─ training                     # Training Group
        ├─ supervised.yaml              # The configuration for   supervised training of PoseNet
        ├─ unsupervised.yaml            # The configuration for unsupervised training of PoseNet 
    ├─ deep_odometry.yaml           # Configuration file for full Deep LiDAR odometry
    ├─ icp_odometry.yaml            # Configuration file for ICP Frame-to-Model odometry
    └─ train_posenet.yaml           # Configuration file to traing PoseNet

To change a named variable within a specific configuration, is done as follows:

python run.py <config-path-to-variable>.<var_name>=<value>

For root variables, which are not defined in the .yaml files (but in the Structured Config dataclasses), you might also need to append a + to the variable declaration (Hydra will complain if this is the case):

python train.py +num_workers=4 +device=cuda:0

Hydra generates a lot of outputs (at each run). You can use the options hydra.run.dir=<path-to-desired-output-dir> to structure the output directories (see below)

Hydra will raise Exceptions on invalid configurations. See hydra documentation for more details.

Using pyLIDAR-SLAM (with hydra):

pyLIDAR-SLAM proposes two scripts run.py and train.py which run with hydra's configuration generation (notably hydra's configuration verification).

Hydra comes with many perks designed for a research workflow (multiple runs with grids of arguments, automatic setting of output directories, etc..). But requires an effort to get into: hydra's enforced rigidity often leads to many configuration errors. Read carefully hydra's error messages which give clues to the configuration errors

Running the SLAM

The script run.py executes the SLAM algorithm defined by the configuration on the datasets defined in the configuration. More specifically, it will:

  • Load all sequences of the given dataset
  • Sequentially launch the SLAM on each sequence
  • Output the estimated trajectory in the allocated folder
  • And if the sequence has defined ground truth poses, computes and saves the trajectory error.

The following example runs a Projective Frame-to-Model Odometry on the sequences of KITTI dataset, using the device cuda:0:

# Set up the following required environment variables
export KITTI_ODOM_ROOT=<path-to-kitti-odometry-root-directory>     # The path to KITTI odometry benchmark files

# Run the script
python run.py dataset=kitti num_workers=4 device=cuda:0 slam/odometry/local_map=projective \
       slam/initialization=CV slam.odometry.local_map.num_neighbors_normals=15

The output files (configuration files, logs, and optionally metrics on the trajectory) will be saved by default at location :

.outputs/slam/<date_time>/.

Note: The output directory can be changed, using arguments hydra.run.dir=<path-to-output-dir>.

Training PoseNet:

The script train.py launches a training of PoseNet on a specified dataset. The script will:

  • Load all train, test and eval sequences from the Dataset
  • For each epoch, update the running PoseNet model in memory
  • Save the model at a specified given location

The following example launches a training of Posenet on KITTI Dataset, for 100 epochs:

export KITTI_ODOM_ROOT=<path-to-kitti-odometry-root-directory>     # The path to KITTI odometry benchmark files
export TRAIN_DIR=<absolute-path-to-the-desired-train-dir>          # Path to the output models 

# Launches the Training of PoseNet
python train.py +device=cuda:0 +num_workers=4 +num_epochs=100 dataset=kitti

/!\ The working directory of the script is controlled by hydra, so beware of relative paths!

The output files are saved by default at:

.outputs/training/posenet_kitti_unsupervised/.          ===> Training files
.outputs/.training/<date_time>/.             ===> Hydra logs and config files for the current run
Clone this wiki locally