131 lines
5.0 KiB
Plaintext
131 lines
5.0 KiB
Plaintext
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" --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" --with-toolbox=$HOME/toolbox/
|
|
|
|
For Performance:
|
|
./configure CXXFLAGS="-DNDEBUG -O3" LDFLAGS="-O3" --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.
|
|
|