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 also included.

GTSAM is not (yet) open source: See COPYING & LICENSE
Please see USAGE for an example on how to use GTSAM.

The code is organized according to the following directory structure:
 
  3rdparty    local copies of third party libraries - Eigen3 and CCOLAMD
  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
  
This library contains unchanged copies of two third party libraries, with documentation 
of licensing in LICENSE and as follows: 
  - CCOLAMD 2.73: Tim Davis' constrained column approximate minimum degree ordering library
  	- http://www.cise.ufl.edu/research/sparse
  	- Licenced under LGPL v2.1, provided in gtsam/3rdparty/CCOLAMD/Doc/lesser.txt
 	- Eigen 3.0.1:  General C++ matrix and linear algebra library
 		- Licenced under LGPL v3, provided in gtsam/3rdparty/Eigen/COPYING.LGPL
  
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, which test the entire library:  
  
  tests       more involved tests that depend on slam
  examples    Demo applications as a tutorial for using gtsam

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

  CppUnitLite unit test library
  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)

2)
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.

3)
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" 

For Debugging (Linux or MacPorts g++ compilers):
./configure CXXFLAGS="-fno-inline -g -Wall -D_GLIBCXX_DEBUG" \
    LDFLAGS="-fno-inline -g -Wall" 

For Performance:
./configure CXXFLAGS="-DNDEBUG -O3" LDFLAGS="-O3" 

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.