Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/simondlevy/BreezySLAM

Simple, efficient, open-source package for Simultaneous Localization and Mapping
https://github.com/simondlevy/BreezySLAM

Last synced: 11 days ago
JSON representation

Simple, efficient, open-source package for Simultaneous Localization and Mapping

Awesome Lists containing this project

README 

        
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](https://github.com/simondlevy/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.