BreezySLAM

This repository contains everything you need to start working with Lidar -based SLAM in Python. (There is also support for Matlab, C++, and Java; however, because of the popularity of Python for this kind of work, I am no longer updating the code for those languages.) BreezySLAM works with Python 3 on Linux and Mac OS X, and with C++ on Linux and Windows. By using Python C extensions, we were able to get the Python and Matlab versions to run as fast as C++. For maximum efficiency on 32-bit platforms, we use Streaming SIMD extensions (Intel) and NEON (ARMv7) in the compute-intensive part of the code.

BreezySLAM was inspired by the Breezy approach to Graphical User Interfaces developed by my colleague Ken Lambert: an object-oriented Application Programming Interface that is simple enough for beginners to use, but that is efficient enough to scale-up to real world problems; for example, the mapping of an entire floor of a house, shown in the image above-right, made by a BreezySLAM user.

As shown in the following code fragment, the basic API is extremely simple: a constructor that accepts Lidar parameters and the size of the map (pixels) and mapping area (meters); a method for updating with the current scan; a method that returns the current robot position; and a method for retrieving the current map as a byte array.

from breezyslam.algorithms import RMHC_SLAM

lidar = MyLidarModel()

mapbytes = bytearray(800*800)

slam = RMHC_SLAM(lidar, 800, 35) 

while True:

    scan = readLidar()

    slam.update(scan)

    x, y, theta = slam.getpos(scan)

    slam.getmap(mapbytes)

If odometry is available, it can also be passed into the update method.

Installing for Python

The BreezySLAM installation uses the popular distutils approach to installing Python packages, so all you should have to do is download and unzip the file, cd to BreezySLAM/python, and do

sudo python3 setup.py install

For a quick demo, you can then cd to BreezySLAM/examples and do

make pytest

This will generate and display a PGM file showing the map and robot trajctory for the Lidar scan and odometry data in the log file exp2.dat. If you have the Python Imaging Library installed, you can also try the log2png.py script to generate a a PNG file instead.

If you have installed PyRoboViz, you can see a “live” animation by doing

make movie

You can turn off odometry by setting the USE_ODOMETRY parameter at the top of the Makefile to 0 (zero). You can turn off the particle-filter (Monte Carlo position estimation) by commenting-out RANDOM_SEED parameter.

To see what other features are available, do

pydoc3 breezyslam

By using the component classes Map, Scan, and Position and the distanceScanToMap() method, you can develop new algorithms and particle filters of your own.

Testing with the Hokuyo URG04LX

If you're running on Linux, you can install the BreezyLidar package, the OpenCV Python package, and try the urgslam.py example in the examples folder.

Testing with the GetSurreal XV Lidar

BreezySLAM includes Python support for the inexpensive XV Lidar from GetSurreal. To try it out, you'll also need the xvlidar Python package. Once you've installed both packages, you can run the xvslam.py example in the BreezySLAM/examples folder.

Testing with the SLAMTEC RPLidar A1

BreezySLAM also includes partial Python support for the inexpensive RPLidar A1 from SLAMTECH. To try it out, you'll also need the rplidar Python package. Once you've installed that package, you can run the rpslam.py example in the BreezySLAM/examples folder.

Unfortunately, I and several users have had trouble using BreezySLAM with the RPLidar A1. The issues are inconsistent enough that I cannot provide support for this lidar unit if you run into trouble using it with BreezySLAM.

Installing for Matlab

I have run BreezySLAM in Matlab on 64-bit Windows, Linux, and Mac OS X. The matlab directory contains all the code you need, including pre-compiled binaries for all three operating systems. To try it out in Matlab, add this directory to your path, then change to the examples directory and do

  >> logdemo('exp2', 1)

If you modify the source code or want to build the binary for a different OS, you can change to the matlab directory and do

  >> make

For making the binary on Windows I found these instructions very helpful when I ran into trouble.

Installing for C++

Just cd to BreezySLAM/cpp, and do

sudo make install

This will put the libbreezyslam shareable library in your /usr/local/lib directory. If you keep your shared libraries elsewhere, just change the LIBDIR variable at the top of the Makefile. You may also need to add the following line to your ~/.bashrc file:

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib

For a quick demo, you can then cd to BreezySLAM/examples and do

make cpptest

Again, you'll need to change the LIBDIR variable at the top of the Makefile in this directory as well, if you don't use /usr/local/lib.

Installing for Java

In BreezySLAM/java/edu/wlu/cs/levy/breezyslam/algorithms and BreezySLAM/java/edu/wlu/cs/levy/breezyslam/components, edit the JDKINC variable in the Makefile to reflect where you installed the JDK. Then run make in these directories.

For a quick demo, you can then cd to BreezySLAM/examples and do

make javatest

Notes on Windows installation

Because of the difficulties that I and others have had installing Python extensions on Windows, I am no longer supporting the Python version of this package on Windows. If you want to try it yourself, here are some instructions.

To build and use the C++ library on Windows, I used MinGW. Whatever C++ compiler you use, you'll have to add the location of the .dll file to your PATH environment variable in the Advanced Systems Settings.

Adding new particle filters

Because it is built on top of the CoreSLAM (tinySLAM) code base, BreezySLAM provides a clean separation between the map-building and particle-filtering (Monte Carlo position estimation) components of SLAM. To add a new particle filter, you can subclass breezyslam.algorithms.CoreSLAM or breezyslam.algorithms.SinglePositionSLAM classes, implementing the relevant methods.

Copyright, licensing, and questions

Copyright and licensing information (Gnu LGPL) can be found in the header of each source file.

Personnel

Suraj Bajracharya, Simon D. Levy, Matt Lubas, Alfredo Rwagaju

Acknowledgments

This work was supported in part by a Commonwealth Research Commercialization Fund grant from the Center for Innovative Technology (CRCF #MF14F-011-MS). We thank Michael Searing of Olin College for his help in debugging and testing this package.