gtsam/README

README - Georgia Tech Smoothing and Mapping library
---------------------------------------------------

What is GTSAM ?

  GTSAM is a library of C++ classes that implement smoothing and
  mapping (SAM) in robotics and vision, using factor graphs and Bayes
  networks as the underlying computing paradigm rather than sparse
  matrices. A set of MATLAB mex wrappers is included.

GTSAM is not (yet) open source: See COPYING & LICENSE

The code is organized according to the following directory structure:

  base				provides some base Math and data structures, as well as test-related utilities
  geometry		points, poses, tensors, etc
  inference		core graphical model inference such as factor graphs, junction trees, Bayes nets, Bayes trees 
  linear			inference specialized to Gaussian linear case, GaussianFactorGraph etc...
  nonlinear		non-linear factor graphs and non-linear optimization
  slam				SLAM and visual SLAM application code
  
All of the above contain code and tests, and build local shared libraries that are then
bundled in a top-level shared library libgtsam.la. After this is built, you can also run
the more involved tests that test the entire library:  
  
  tests				more involved tests that depend on slam

Furthermore the MATLAB wrapper generator code is run as well

  wrap				MATLAB wrapper generation code
  gtsam.h			interface file for which wrappers will be generated
  toolbox			MATLAB proxy classes and wrappers generated
  matlab			examples and tests of the above  		

Finally, there are some local libraries built needed in the rest of the code:

  colamd			COLAMD and CCOLAMD by Tim Davis needed for re-ordering
  CppUnitLite	unit test library
  doc					documentation
  m4					local M4 macros


Important Installation Notes Specific to GTSAM
----------------------------------------------

1)
GTSAM requires the following libraries to be installed on your system:
 - BOOST version 1.40 or greater (install through Linux repositories or MacPorts)
 - BLAS, ATLAS, and LAPACK (libblas, libatlas, and liblapack in Debian/Ubuntu
                            repositories, on Mac these should already installed
                            with the OS)

2)
GTSAM uses CCOLAMD to find good variable elimination orders.  You can download
it from Tim Davis's website:  http://www.cise.ufl.edu/research/sparse/ccolamd/
Then, pass the following arguments (paths are just examples) to ./configure:
--with-ccolamd-inc=/usr/local/include
--with-ccolamd-lib=/usr/local/lib

3)
GTSAM makes extensive use of debug assertions, even for checking input of
the functions you will call.  These assertions are disabled when NDEBUG is
defined.  Thus, we strongly recommend compiling GTSAM and your own code without
this symbol during debugging.

After debugging, GTSAM will run much faster when compiled with NDEBUG defined,
so that debug checks are disabled.

Another useful debugging symbol is _GLIBCXX_DEBUG, which enables debug checks
and safe containers in the standard C++ library and makes problems much easier
to find.
NOTE:  The native Snow Leopard g++ compiler/library contains a bug that makes
it impossible to use _GLIBCXX_DEBUG.  MacPorts g++ compilers do work with it though.

4)
Putting the above together, here are some sample ./configure commands for
compiling gtsam:

For Debugging (native Snow Leopard g++ compiler):
./configure CXXFLAGS="-fno-inline -g -Wall" \
    LDFLAGS="-fno-inline -g -Wall" --enable-blas --enable-lapack \
    --with-toolbox=$HOME/toolbox/

For Debugging (Linux or MacPorts g++ compilers):
./configure CXXFLAGS="-fno-inline -g -Wall -D_GLIBCXX_DEBUG" \
    LDFLAGS="-fno-inline -g -Wall" --enable-blas --enable-lapack \
    --with-toolbox=$HOME/toolbox/

For Performance:
./configure CXXFLAGS="-DNDEBUG -O3" LDFLAGS="-O3" --enable-blas \
    --enable-lapack --with-toolbox=$HOME/toolbox/

After that (this would be for an in-source build, see next for out-of-source):
$ make
$ make check (optional, runs unit tests)
$ make install


Out-of-source build:
--------------------
The above will put object files and executables in the source directories. If you like, it is 
very easy to configure the libraries to put all these in a parallel build tree so they do not 
clutter the source tree. To do this, instead of running configure in the gtsam directory itself, 
run it in sub-directory of choice, e.g., starting out in the main GTSAM folder:

$] mkdir build
$] cd build
$] ../configure ..... (command as above)
$] make install


Built-in Unit Tests:
--------------------
There is one more optional step in which you can invoke the unit tests included in the gtsam libraries. 
$] make check
By verifying all the test results are positive, you can make sure that the functionalities of the GTSAM
libraries are correct.


Compile Matlab Toolbox:
-----------------------
1) Start Matlab
2) Go to File->Set Path and add the toolbox directory where you installed the
   GTSAM Matlab Toolbox
3) Change your current directory to the GTSAM Matlab Toolbox
4) Type 'make_gtsam' at the Command Window


Run Matlab Unit Tests:
-----------------------
In the matlab command window, change directory to $gtsam/matlab and then type 'run_tests', which will 
invoke the matlab unit tests.