163 lines
6.8 KiB
Plaintext
163 lines
6.8 KiB
Plaintext
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 library 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.5: General C++ matrix and linear algebra library
|
|
- Licenced under LGPL v3, provided in gtsam/3rdparty/Eigen/COPYING.LGPL
|
|
|
|
|
|
There are two supporting libraries:
|
|
|
|
CppUnitLite unit test library customized for use with gtsam
|
|
wrap code generation utility for the Matlab interface to gtsam
|
|
|
|
Important Installation Notes
|
|
----------------------------
|
|
|
|
1)
|
|
GTSAM requires the following libraries to be installed on your system:
|
|
- BOOST version 1.43 or greater (install through Linux repositories or MacPorts)
|
|
- Cmake version 2.6 or higher
|
|
- Support for XCode 4.3 command line tools on Mac requires CMake 2.8.8 or higher
|
|
|
|
Tested compilers
|
|
- GCC 4.2-4.7
|
|
- Clang 2.9-3.2
|
|
- OSX GCC 4.2
|
|
|
|
Tested systems:
|
|
- Ubuntu 11.04, 11.10, 12.04
|
|
- MacOS 10.6, 10.7
|
|
|
|
2)
|
|
GTSAM makes extensive use of debug assertions, and we highly recommend you work
|
|
in Debug mode while developing (enabled by default). Likewise, it is imperative
|
|
that you switch to release mode when running finished code and for timing. GTSAM
|
|
will run up to 10x faster in Release mode! See the end of this document for
|
|
additional debugging tips.
|
|
|
|
3)
|
|
GTSAM has Doxygen documentation. To generate, run the the script
|
|
makedoc.sh.
|
|
|
|
4)
|
|
The instructions below install the library to the default system install path and
|
|
build 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.
|
|
|
|
- CMake Configuration 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 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".
|
|
|
|
Debugging tips:
|
|
|
|
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.
|