186 lines
6.8 KiB
Markdown
186 lines
6.8 KiB
Markdown
BreezySLAM
|
|
==========
|
|
|
|
<img src="breezyslam.png" align="center" width=700>
|
|
|
|
<p><p><p>
|
|
|
|
<b>Simple, efficient, open-source package for Simultaneous Localization and Mapping in Python and C++</b>
|
|
|
|
<a href="https://github.com/simondlevy/BreezySLAM">This repository</a> contains everything you need to
|
|
start working with
|
|
<a href="http://en.wikipedia.org/wiki/Lidar">Lidar</a>
|
|
-based
|
|
<a href="http://en.wikipedia.org/wiki/Simultaneous_localization_and_mapping">SLAM</a>
|
|
in Python or C++. (For those interested in Matlab or Java, there is a
|
|
[legacy](https://github.com/simondlevy/BreezySLAM/tree/legacy) branch, which I
|
|
am no longer maintaining.) BreezySLAM works with Python 2 and 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 version to run as fast as C++. For maximum effiency
|
|
on 32-bit platforms, we use Streaming SIMD extensions (Intel) and NEON (ARMv7)
|
|
in the compute-intensive part of the code.
|
|
</p><p>
|
|
BreezySLAM was inspired by the <a href="http://home.wlu.edu/%7Elambertk/#Software">Breezy</a>
|
|
approach to Graphical User Interfaces developed by my colleague
|
|
<a href="http://home.wlu.edu/%7Elambertk/">Ken Lambert</a>: 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
|
|
<a href="https://www.linkedin.com/pulse/slam-your-robot-drone-python-150-lidar-chris-fotache">user</a>.
|
|
|
|
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.
|
|
|
|
<pre>
|
|
from breezyslam.algorithms import RMHC_SLAM
|
|
|
|
lidar = MyLidarModel()
|
|
|
|
mapbytes = bytearray(800*800)
|
|
|
|
slam = <b>RMHC_SLAM</b>(lidar, 800, 35)
|
|
|
|
while True:
|
|
|
|
scan = readLidar()
|
|
|
|
slam.update(scan)
|
|
|
|
x, y, theta = slam.<b>getpos</b>(scan)
|
|
|
|
slam.getmap(mapbytes)
|
|
</pre>
|
|
|
|
If odometry is available, it can also be passed into the update method.
|
|
|
|
|
|
</p><h3>Installing for Python</h3>
|
|
|
|
<p>
|
|
The BreezySLAM installation uses the popular
|
|
<a href="http://docs.python.org/2/distutils/introduction.html">distutils</a>
|
|
approach to installing Python packages, so all you should have to do is
|
|
download and unzip the file, cd to <tt><b>BreezySLAM/python</b></tt>, and do
|
|
|
|
<pre>
|
|
sudo python3 setup.py install
|
|
</pre>
|
|
|
|
For a quick demo, you can then cd to <tt><b>BreezySLAM/examples</b></tt> and do
|
|
|
|
<pre>
|
|
make pytest
|
|
</pre>
|
|
|
|
|
|
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
|
|
<tt><b>exp2.dat</b></tt>. If you have the
|
|
<a href="http://www.pythonware.com/products/pil/">Python Imaging Library</a> installed,
|
|
you can also try the <b><tt>log2png.py</tt></b> script to generate a
|
|
a PNG file instead.
|
|
|
|
If you have installed Matplotlib, you can see a “live” animation
|
|
by doing
|
|
|
|
<pre>
|
|
make movie
|
|
</pre>
|
|
|
|
You can turn off odometry by setting the <b><tt>USE_ODOMETRY</tt></b>
|
|
parameter at the top of the Makefile to 0 (zero). You can turn off
|
|
the particle-filter (Monte Carlo position estimation) by commenting-out
|
|
<b><tt>RANDOM_SEED</tt></b> parameter.
|
|
|
|
<p>
|
|
|
|
To see what other features are available, do
|
|
|
|
<pre>
|
|
pydoc3 breezyslam
|
|
</pre>
|
|
|
|
By using the component classes <b>Map</b>, <b>Scan</b>, and
|
|
<b>Position</b> and the <b>distanceScanToMap()</b> method,
|
|
you can develop new algorithms and particle filters of your own.
|
|
|
|
<p><h3>Testing with the Hokuyo URG04LX</h3>
|
|
|
|
If you're running on Linux, you can install the <a href="http://home.wlu.edu/~levys/software/breezylidar/">BreezyLidar</a> package, the OpenCV Python package, and
|
|
try the <b>urgslam.py</b> example in the examples folder.
|
|
|
|
<p><h3>Testing with the GetSurreal XV Lidar</h3>
|
|
|
|
BreezySLAM now includes Python support for the inexpensive
|
|
<a href="https://www.getsurreal.com/product/xv-lidar-sensor-mount-package">XV Lidar</a> from GetSurreal.
|
|
To try it out, you'll also need the <a href="https://github.com/simondlevy/xvlidar">xvlidar</a>
|
|
Python package. Once you've installed
|
|
both packages, you can run the <b>xvslam.py</b> example in the <b>BreezySLAM/examples</b> folder.
|
|
|
|
<h3>Installing for C++</h3>
|
|
|
|
Just cd to <tt><b>BreezySLAM/cpp</b></tt>, and do
|
|
|
|
<h3><b><tt>sudo make install</tt></b></h3>
|
|
|
|
This will put the <tt><b>libbreezyslam</b></tt> shareable library in your <tt><b>/usr/local/lib</b></tt>
|
|
directory. If you keep your shared libraries elsewhere, just change the <tt><b>LIBDIR</b></tt>
|
|
variable at the top of the Makefile.
|
|
|
|
<p>
|
|
|
|
For a quick demo, you can then cd to <tt><b>BreezySLAM/examples</b></tt> and do
|
|
|
|
<pre>
|
|
make cpptest
|
|
</pre>
|
|
|
|
<p>
|
|
|
|
Again, you'll need to change the <tt><b>LIBDIR</b></tt> variable at the top of
|
|
the Makefile in this directory as well, if you don't use <tt><b>/usr/local/lib</b></tt>.
|
|
|
|
</p><p>
|
|
|
|
<h3>Notes on Windows installation</h3>
|
|
|
|
|
|
Because of the
|
|
<a href="http://stackoverflow.com/questions/2817869/error-unable-to-find-vcvarsall-bat">difficulties</a> 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, <a href="https://docs.python.org/2/extending/windows.html">here</a> are some instructions.
|
|
<p>
|
|
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 <tt><b>.dll</b></tt> file to your
|
|
<tt><b>PATH</b></tt> environment variable in the Advanced Systems Settings.
|
|
|
|
<h3>Adding new particle filters</h3>
|
|
|
|
Because it is built on top of the CoreSLAM (<a href="https://openslam.org/tinyslam.html">tinySLAM</a>) 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
|
|
<a href="doc/breezyslam.algorithms.html#CoreSLAM">breezyslam.algorithms.CoreSLAM</a> or
|
|
<a href="doc/breezyslam.algorithms.html#SinglePositionSLAM">breezyslam.algorithms.SinglePositionSLAM</a>
|
|
classes, implementing the relevant methods.
|
|
|
|
|
|
<h3>Copyright, licensing, and questions</h3>
|
|
|
|
Copyright and licensing information (Gnu
|
|
<a href="https://www.gnu.org/licenses/lgpl.html">LGPL</a>)
|
|
can be found in the header of each source file.
|
|
|
|
<h3>Personnel</h3>
|
|
|
|
Suraj Bajracharya, Simon D. Levy, Matt Lubas, Alfredo Rwagaju
|
|
|
|
<h3>Acknowledgments</h3>
|
|
|
|
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.
|