***** ScaViSLAM *****

This is a general and scalable framework for visual SLAM. It employs 
"Double Window Optimization" (DWO) as described in our ICCV paper:

H. Strasdat, A.J. Davison, J.M.M. Montiel, and K. Konolige
"Double Window Optimisation for Constant Time Visual SLAM"
Proceedings of the IEEE International Conference on Computer Vision, 2011.

At the moment it supports calibrated stereo rigs, and RGB-D cameras.
Monocular SLAM is NOT supported (yet).

*** NOTES AND WARNINGS / READ FIRST ***

This library is a research-level software which is in development. 
This is NOT a release version. For sure, features will be added, 
bugs will be fixed and the API will change in the future.

Even thought the software is in principal designed to run cross-platform,
it most likely will only work on a recent 64-bit linux (without the need
of adaptations...). It was tested on Ubuntu 11.10 - 64 bit.

(Note there might be problems on 32bit linux related to Eigen3.
 http://eigen.tuxfamily.org/dox/TopicUnalignedArrayAssert.html.
 I followed the guide describe on this website, but I have not tested it on 
 32-bit linux yet. Any bug reports/patches are welcome!)

WARNING: There is a bug concerning Eigen3 and gcc/g++-4.4. Do not compile
ScaViSLAM, g2o, etc. using gcc/g++-4.4! It will compile but might produce wrong
results! 
(see: http://listengine.tuxfamily.org/lists.tuxfamily.org/eigen/2011/04/msg00013.html
&  http://comments.gmane.org/gmane.comp.lib.eigen/2046)
Detailed instructions are listed below.


*** INSTALLATION ***

First download sample image sequences. This will take a while, so do it first.
(These are already rectified stereo images from the New College dataset: 
http://www.robots.ox.ac.uk/NewCollegeData/)

>>
cd MY_DATA_DIRECTORY
mkdir newcollege
cd newcollege
wget -nH --cut-dirs=4 -r -l2 --no-parent -A "*.pnm" http://pub1.willowgarage.com/~konolige/data/NewCollege/FullData/StereoImages_1225720041.455302_to_1225720118.251935 
wget -nH --cut-dirs=4 -r -l2 --no-parent -A "*.pnm" http://pub1.willowgarage.com/~konolige/data/NewCollege/FullData/StereoImages_1225720118.301927_to_1225720193.248630
wget -nH --cut-dirs=4 -r -l2 --no-parent -A "*.pnm" http://pub1.willowgarage.com/~konolige/data/NewCollege/FullData/StereoImages_1225720193.298630_to_1225720268.945303
<<

Before we start with the installation, we need to perform some preparations.
ScaViSLAM comes with GPU support. Indeed, GPU support is the default option.
(Each GPU method has a CPU equivalent. However those are not tested very much).
Thus, there is an optional dependency on CUDA 4.0 or higher.

First, find out your compiler version by typing "g++ -v".
There are three options:

 Version 4.5 or higher: Everything is fine. 
  However, CUDA requires gcc 4.4. If you want to use CUDA and you have not 
  done it yet, proceed with the following steps:
   1. <<
        sudo apt-get install gcc-4.4 g++-4.4 
      >>
   2. >>
        sudo mkdir /usr/local/bin/gnuc4.4
        sudo ln -s /usr/bin/gcc-4.4 /usr/local/bin/gnuc4.4/gcc
        sudo ln -s /usr/bin/g++-4.4 /usr/local/bin/gnuc4.4/g++
        sudo ln -s /usr/bin/c++-4.4 /usr/local/bin/gnuc4.4/c++
      <<
   3. Then, add the line "compiler-bindir=/usr/local/bin/gnuc4.4" to
      "/usr/local/cuda/bin/nvcc.profile".
  (Description how to install CUDA 4.0 on a newer version of Ubuntu:
   http://hdfpga.blogspot.com/2011/05/install-cuda-40-on-ubuntu-1104.html)

 Version 4.4: Because of the problem with Eigen (see above), you NEED to install 
  a newer version of gcc and g++ (4.5, 4.6 ,4.7 ...). Make sure that ScaViSLAM 
  and all EXTERNAL dependencies are compiled with the newer version. Note, that
  CUDA 4.0 still depends on gcc 4.4. 
  (One option is to set the default compilers to 4.5. Thus, "gcc -v", "g++ -v" and
   "c++ -v" will report 4.5 and you can proceed which the steps 2.-3. above.) 

 Version 4.3 or lower: You are using an old or custom version of linux. This is
  not supported by this installation guideline. 
  (It might work, but I guess you have to disable CUDA support.)

Next, install dependencies:

>>
sudo apt-get install freeglut3-dev libglu-dev libglew-dev libboost-all-dev
<<

(This is an incomplete list at the moment, since it is hard to guess which 
 libraries are installed by default on your linux distribution...)

Now, checkout/clone the ScaViSLAM repository.

>>
cd MY_SOFTWARE_DIRECTORY
git clone git@github.com:strasdat/ScaViSLAM.git
<<

Now, enter the project directory

>>
cd ScaViSLAM
<<

and then create and enter the directory for EXTERNAL libraries:

>>
mkdir EXTERNAL
cd EXTERNAL
<<

The ScaViSLAM build system is designed in a way such that all 
dependencies are installed locally in a sub-folder. In this way we avoid
version conflicts (e.g. different OpenCV version which might be installed
system-wide). Please follow the guide step by step and only deviate form 
it if you really know what you are doing ;-)

Download Eigen (version 3.0.3) in folder EXTERNAL

>>
wget http://bitbucket.org/eigen/eigen/get/3.0.3.tar.bz2
tar xvf 3.0.3.tar.bz2
mv eigen-eigen-3.0.3/ eigen3
<<

Check out and install g2o (fork of the g2o release hosted at openslam.org):

>>
git clone git@github.com:strasdat/g2o-fork.git g2o
cd g2o
mkdir svs_build
cd svs_build
cmake ..
make -j8
cd ../..
<<

Download and install opencv (version 2.3.1a) inside EXTERNAL:

>>
wget http://sourceforge.net/projects/opencvlibrary/files/opencv-unix/2.3.1/OpenCV-2.3.1a.tar.bz2
tar xvf OpenCV-2.3.1a.tar.bz2
mv OpenCV-2.3.1 opencv2
cd opencv2
mkdir svs_build
cd svs_build
cmake ..
<<

If you wish to use CUDA support, which is highly recommended, make
sure OpenCV recognizes CUDA ("Use Cuda:                   YES"
in "Other third-party libraries" section). Note that CUDA 4.0 or higher is
required.

>>
make -j8
<<

In case you get an compiler error in "cap_ffmpeg.cpp", simply 
deactivate "USE_FFMPEF", e.g. using cmake-gui.

>>
cd ../..
<<

Clone and install Pangolin (68d75c2d54450d90efd2e6e2cfcd72a6a599ef58)

>>
git  clone -v https://github.com/stevenlovegrove/Pangolin.git
cd Pangolin
git checkout 68d75c2d54450d90efd2e6e2cfcd72a6a599ef58
mkdir svs_build
cd svs_build
cmake ..
make -j8
cd ../..
<<

Clone and install Sophus in folder EXTERNAL

>>
git clone git@github.com:strasdat/Sophus.git
cd Sophus
mkdir svs_build
cd svs_build
cmake ..
make -j8
cd ../..
<<

Install VisionTools in folder EXTERNAL

>>
git clone git@github.com:strasdat/VisionTools.git
cd VisionTools
mkdir svs_build
cd svs_build
cmake ..
make -j8
<<

Move to main project folder "ScaViSLAM" and install ScaViSLAM:

>>
cd ../../../
mkdir svs_build
cd svs_build
cmake ..
make -j8
<<

In case you would like to compile ScaViSLAM WITHOUT CUDA support, type
"cmake -DCUDA_SUPPORT=OFF .." instead of "cmake .."

Make sure the "New College" data set is downloaded completely.
Then add a sym-link inside "ScaViSLAM/data":

>>
cd ../data
ln -s PATH_TO_MY_DATA_DIRECTORY/newcollege newcollege
<<

Run ScaViSLAM on new college image sequence:
>>
cd ../svs_build
./stereo_slam ../data/newcollege.cfg
<<


*** HOW TO USE A RGB-D CAMERA? ***

At the moment, only RGB-D cameras following the PrimeSense reference design
(e.g. Ausus Xtion PRO LIVE) are supported.
First, you need to install PCL (which includes OpenNI):

>>
sudo add-apt-repository ppa:v-launchpad-jochen-sprickerhof-de/pcl
sudo apt-get update
sudo apt-get install libpcl-all
<<

Reinstall ScaViSLAM with PCL support:

>>
cd MY_SOFTWARE_DIRECTORY
cd /ScaViSLAM/
mkdir svs_build_with_pcl
cd svs_build_with_pcl
cmake  -DPCL_SUPPORT=ON ..
make -j8
>>

Try out ScaViSLAM with your RGB-D camera life:

>>
./stereo_slam ../data/rgbd-Live.cfg
<<

Dump RGB-D data to the hard disk (to ../data/out; create this directory or 
set an appropriate sym-link):

>>
./dump_rgbd ../data/rgbd_live.cfg 
<<

Finally, you can process the saved image sequence by adapting the configuration 
files "../data/rgbd_example.cfg". Basically, you have to point
"framepipe.path_str" to the saved images.


*** WHAT ABOUT STANDARD STEREO CAMERAS? ***

This is more tricky since we need to make sure that the image stream is 
rectified. Some adaptation in the code might be necessary...


*** HOW TO CONTRIBUTE? ***

You are welcome to report bugs and request features at: 
https://github.com/strasdat/ScaViSLAM/issues.
To do so click on "New Issue", fill out the form and select the appropriate
label ("Bug" or "Feature Request").
Please feel free to also browse through the "ToDo" and "Future Features" 
issues, so you can find out which features are planned to be included 
soon ("ToDo") or eventually ("Future Features").

The best and easiest  way to contribute is to use the "github" way:
 - Register at github (for free).
 - Got to: "https://github.com/strasdat/ScaViSLAM"
 - Click on "Fork" to create a Fork of ScaViSLAM.
 - Commit and push changes into your Fork.
 - Click on "Pull Request" in order to ask me whether I would like to merge
   the changes into the ScaViSLAM master branch.

(If it is only a small change/bug fix, you could also simply send me
patch etc.)

In order to maximize the likelihood that I will accept your pull request,
please read carefully through the coding style guide:


*** CODING STYLE GUIDE ***

The coding style is largely influenced by the google c++ coding style guide:
http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml
(Reading the document is insightful in any case, even if you don't agree with
"google's" decision!)

I am especially strict about the following rules:

 - "When defining a function, parameter order is: inputs, then outputs."
 - "All parameters passed by reference must be labeled const."
   Thus, the following is NOT okay:
   'void method(const Vector2d & in, Vector2d & out)'
   Use this instead:
   'void method(const Vector2d & in, Vector2d * out)'
 - "Of the built-in C++ integer types, the only one used is int. If a program 
    needs a variable of a different size, use a precise-width integer type 
    from <stdint.h>, such as int16_t."
 - "Use 0 for integers, 0.0 for reals, NULL for pointers, and '\0' for chars."
 - "We do not use C++ exceptions."
 - "Use the specified order of declarations within a class: public: before 
    private:, methods before data members (variables), etc." 
 - "Use a struct only for passive objects that carry data; everything else 
    is a class."
 - "Prefer small and focused functions."
 - "Use only approved libraries and language extensions from C++11 (formerly 
    known as C++0x). Currently, none are approved."
 - "We do not allow default function parameters, except in a few uncommon 
    situations..."
 - "Use prefix form (++i) of the increment and decrement operators with 
    iterators and other template objects."
 - "We strongly recommend that you use const whenever it makes sense to do so."

At some points, I deviate from the C++ coding style guide:
 - 'Using namespace X;' is okay, but only within(!) the ScaViSLAM namespace.
   Never pollute the general namespace '::'. 
   (However, do not use "using namespace cv" or 'using namespace pangolin'.) 
 - I use 'boost::thread'.
 - In rare cases, it is okay to have public class members.
 - It is okay to use streams such as "cout", "cerr", "stringstream". (But 
   usually, I'd like to use "cerr" and friends only for debugging purposes...)

I also deviate slightly from google's formatting. Therefore the following rule
is the most important one:

"Use common sense and BE CONSISTENT.

If you are editing code, take a few minutes to look at the code around you and 
determine its style. If they use spaces around their if clauses, you should, 
too. If their comments have little boxes of stars around them, make your 
comments have little boxes of stars around them too." 

(All cites in "quotation marks" are from the google coding style guide.)

If you would like to use automatic indentation, I recommend you to use
the QtCreator (1.4.0 or newer) for code editing. You can import the ScaViSLAM
code style using "coding_style.xml":
 * Open "ScaViSLAM" project in QtCreator.
 * Click on "Projects". (Select "ScaViSLAM" tap in case several projects are 
   open.)
 * Click on "Editor Settings". 
 * Select "Editor Settings: Custom"
 * Click on "Coding Style Settings-->Import..." and select "coding_style.xml".