gtsam/README

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

Quickstart

In the root library folder execute:

$] mkdir build
$] cd build
$] cmake ..
$] make check (optional, runs unit tests)
$] make install

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. 

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

The core GTSAM code within the folder gtsam, with source, headers, and 
unit tests. After building, this will generate a single library "libgtsam"

The libgtsam 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

Additionally, in the SVN development version of GTSAM, there is an area for 
unstable code directly under development in the folder gtsam_unstable, which contains 
a directory structuring mirroring the libgtsam structure as necessary.  This section produces
a single library "libgtsam_unstable".  Building of gtsam_unstable is disabled by default, see
CMake configuration options for information on enabling building.

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.5:  General C++ matrix and linear algebra library
    - Licenced under LGPL v3, provided in gtsam/3rdparty/Eigen/COPYING.LGPL

After this is built, you can also run the more involved tests, which test the entire library:  
  
  tests         More involved unit tests that depend on slam
  examples      Demo applications as a tutorial for using gtsam
  cmake         CMake scripts used within the library, as well as for finding GTSAM by dependent projects

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

  CppUnitLite   unit test library customized for use with gtsam
  wrap          code generation utility for the Matlab interface to gtsam

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)

GTSAM uses CMake (http://www.cmake.org/) for build automation
 - Installed cmake version must be 2.6 or higher

Tested compilers
 - gcc
 - clang
 - OSX gcc

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.

NOTE:  If _GLIBCXX_DEBUG is used to compile gtsam, anything that links against
gtsam will need to be compiled with _GLIBCXX_DEBUG as well, due to the use of
header-only Eigen.  

3)
GTSAM has been written to support the creation of API documentation using
doxygen.  To create html documentation for GTSAM, run the the script 
makedoc.sh.  

4)
After installing prerequisites for building GTSAM, you can configure and build
GTSAM using CMake with the default options with the quickstart options. For 
details on the full functionality of CMake, see the CMake documentation.  

- CMake Quickstart
Installs to the default system install path and builds all components.  From a terminal, 
starting in the root library folder, execute commands as follows for an out-of-source
build:

$] mkdir build
$] cd build
$] cmake ..
$] make check (optional, runs unit tests)
$] make install

This will build the library and unit tests, run all of the unit tests, 
and then install the library itself.

- Additional CMake Options and Details

GTSAM has a number of options that can be configured, which is best done with
one of the following:

  ccmake      the curses GUI for cmake
  cmake-gui   a real GUI for cmake

Important CMake configuration options: 

CMAKE_BUILD_TYPE: We support several build configurations for GTSAM (case insensitive)
  Debug (default)  All error checking options on, no optimization. Use for development.
  Release          Optimizations turned on, no debug symbols.           
  Timing           Adds ENABLE_TIMING flag to provide statistics on operation 
  Profiling        Standard configuration for use during profiling
  RelWithDebInfo   Same as Release, but with the -g flag for debug symbols

CMAKE_INSTALL_PREFIX: The install folder. The default is typically /usr/local/
To configure to install to your home directory, you could execute:
$] cmake -DCMAKE_INSTALL_PREFIX:PATH=$HOME ..

GTSAM_TOOLBOX_INSTALL_PATH: The Matlab toolbox will be installed in a subdirectory
of this folder, called 'gtsam'.
$] cmake -DGTSAM_TOOLBOX_INSTALL_PATH:PATH=$HOME/toolbox ..

GTSAM_BUILD_CONVENIENCE_LIBRARIES: This is a build option to allow for tests in 
subfolders to be linked against convenience libraries rather than the full libgtsam. 
Set with the command line as follows:
$] cmake -DGTSAM_BUILD_CONVENIENCE_LIBRARIES:OPTION=ON ..
  ON (Default)   This builds convenience libraries and links tests against them. This 
  				 option is suggested for gtsam developers, as it is possible to build 
  				 and run tests without first building the rest of the library, and 
  				 speeds up compilation for a single test. The downside of this option 
  				 is that it will build the entire library again to build the full 
  				 libgtsam library, so build/install will be slower.
  OFF            This will build all of libgtsam before any of the tests, and then 
  				 link all of the tests at once. This option is best for users of GTSAM, 
  				 as it avoids rebuilding the entirety of gtsam an extra time. 

GTSAM_BUILD_UNSTABLE: Enable build and install for libgtsam_unstable library. 
Set with the command line as follows:
$] cmake -DGTSAM_BUILD_UNSTABLE:OPTION=ON ..
  ON             When enabled, libgtsam_unstable will be built and installed with the 
                 same options as libgtsam.  In addition, if tests are enabled, the 
                 unit tests will be built as well.  The Matlab toolbox will also
                 be generated if the matlab toolbox is enabled, installing into a 
                 folder called "gtsam_unstable".
  OFF (Default)  If disabled, no gtsam_unstable code will be included in build or install. 

Check

"make check" will build and run all of the tests. Note that the tests will only be 
built when using the "check" targets, to prevent "make install" from building the tests
unnecessarily. You can also run "make timing" to build all of the timing scripts. 
To run check on a particular module only, run "make check.[subfolder]", so to run
just the geometry tests, run "make check.geometry". Individual tests can be run by
appending ".run" to the name of the test, for example, to run testMatrix, run 
"make testMatrix.run".