From 8a4353ba008dd20cad72f549ec911c9936214b41 Mon Sep 17 00:00:00 2001 From: simondlevy Date: Thu, 19 May 2016 18:58:16 -0400 Subject: [PATCH] --- README.md | 197 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 196 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index df2cdce..2a0e485 100644 --- a/README.md +++ b/README.md @@ -3,4 +3,199 @@ BreezySLAM Simple, efficient, open-source package for Simultaneous Localization and Mapping in Python, Matlab, and C++ -See http://home.wlu.edu/~levys/software/breezyslam/ for details. +This repository contains everything you need to +start working with +Lidar +-based +SLAM +in Python, Matlab or C++. 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 and Matlab versions 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. +

+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. +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-master/python, and do + +   

sudo python setup.py install

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

chmod +x log2pgm.py +   

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. +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 + +   

pydoc breezyslam

+ +or check out the online documentation. 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 now 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. + +

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-master/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. + +

+ +For a quick demo, you can then cd to BreezySLAM-master/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-master/java/edu/wlu/cs/levy/breezyslam/algorithms and +BreezySLAM-master/java/edu/wlu/cs/levy/breezyslam/components, +edit the JDKINC variable to reflect where you installed the JDK. +Then run make in these directories, and also in +BreezySLAM-master/java/edu/wlu/cs/levy/breezyslam/robots. + +

+ +For a quick demo, you can then cd to BreezySLAM-master/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 and Simon D. Levy + +

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.