The Borg Lab

GTSAM 3.2.1

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.

On this page:

  1. Download GTSAM 3.2.1 (Latest version)
  2. Documentation
  3. Quickstart (compiling and installing)
  4. Compiling the MATLAB wrapper from source
  5. Tested systems
  6. Known issues

New: The latest development code can now be found at https://bitbucket.org/gtborg/gtsam/. We welcome your contributions and bug reports!

For private feedback and questions please contact us at gtsam@lists.gatech.edu.

3.2.1 (Latest version):

C++ library and optional MATLAB toolbox - Compile from source.  See the Quickstart just below for how to compile.
        Tarball:  gtsam-3.2.1.tgz
        Zip:  gtsam-3.2.1.zip

Precompiled MATLAB toolbox only - Works with MATLAB R2011a and later (Please see the README file to get started):
        Mac OS 64-bit:  gtsam-toolbox-3.2.0-mac64.tgz
        Linux 64-bit: gtsam-toolbox-3.2.0-lin64.tgz
        Windows 64-bit: gtsam-toolbox-3.2.0-win64.zip

Note: There is no change in the Matlab toolboxes since the 3.2.0 release.

If the precompiled MATLAB toolbox packages here do not match your system, you may need to compile the wrapper using the source packages above.

Note: GTSAM is licensed under the BSD license.

Documentation:

Quickstart:

Prerequisites:

  • BOOST version 1.43 or higher (install through Linux repositories or MacPorts)
  • CMake (http://www.cmake.org/) 2.6 or higher

Build and install GTSAM:

GTSAM compiles with the standard CMake procedure.  Here is a brief introduction to compilation with CMake in case you're not familiar with it:

On Linux and Mac:

Open a terminal and change to the top-level GTSAM source tree directory, of the tarball that you unpacked.  Then run:

$ mkdir build
$ cd build
$ cmake ..
$ make check       (optional, runs unit tests)
$ make install
  • The default install path is /usr/local.  If you prefer to change this, replace the above call to cmake with 'cmake -DCMAKE_INSTALL_PREFIX=/your/preferred/install/path'.
  • A Release build is the default.
  • If you find that you need a debug build of GTSAM to track down runtime problems in your project, you may compile and install a Debug GTSAM build to the same location as the Release build if you enable GTSAM_BUILD_TYPE_POSTFIXES in CMake (and then set CMAKE_BUILD_TYPE to Debug).  Our CMake configuration will then automatically link the corresponding Debug or Release GTSAM library to your project, depending on which configuration your project is compiled in.

On Windows:

  1. Open the CMake GUI program - set the source directory to the top-level GTSAM directory that you unpacked, and the build directory to a subdirectory of it, e.g. 'build'.
  2. You may want to change CMAKE_INSTALL_PREFIX to install GTSAM in your home directory instead of in Program Files.  There is no need to set CMAKE_BUILD_TYPE.  You may also set GTSAM_DISABLE_EXAMPLES_ON_INSTALL to speed up the compilation later on.
  3. If Boost is not found automatically, provide hints to CMake by setting CMake variables:
    BOOST_ROOT and BOOST_INCLUDEDIR to the folder where you installed boost. If problems persist, boolean variable Boost_DEBUG can be set to make the FindBoost script verbose.
  4. Click 'Configure', followed by 'Generate'.  The first time you configure, CMake will ask you to choose the compiler.  Choose the Visual Studio option corresponding to whether your Windows installation is 32 or 64 bit, and the version of Visual Studio installed. Do not choose NMake makefiles or Cygwin makefiles, our scripts are not compatible with these.
  5. Open the GTSAM.sln file that is generated in the build directory.  Subsequently, you can re-generate the solution files with MSVC still open and it will automatically reload them.
  6. Set the build configuration (Debug, Release, etc) using the dropdown menu in the Visual Studio toolbar - setting CMAKE_BUILD_TYPE in CMake has no effect (unless building the MATLAB wrapper, see below).
  7. In the solution browser, build the 'INSTALL' project under 'CMakePredefinedTargets'.  Be sure to build 'INSTALL' for both Debug and Release configurations.
  8. If you prefer, it is not necessary to "install" GTSAM to build projects against it. Our CMake configuration will properly find and link to GTSAM. In your project CMake environment set GTSAM_DIR to the GTSAM build directory in which the solution files were generated.

Compiling the MATLAB wrapper from source:

If the above precompiled MATLAB toolbox packages do not work for you, it is straightforward to compile the wrapper from source:

  1. In CMake, enable GTSAM_INSTALL_MATLAB_TOOLBOX.
  2. In CMake, set MEX_COMMAND to the full path and name of the mex program distributed with MATLAB.  Typical paths include:
    Linux:  /usr/local/MATLAB/R2014a/bin/mex
    Mac:  /Applications/MATLAB2014a/bin/mex
    Windows:  C:\Program Files\MATLAB\R2012a\bin\mex.bat
  3. The default install location for the MATLAB wrapper is CMAKE_INSTALL_PREFIX/gtsam_toolbox, but this may be changed by setting GTSAM_TOOLBOX_INSTALL_PATH in CMake.
  4. Note that on Linux and Mac, if the GTSAM and Boost dynamic libraries are not installed into a system path (/usr/lib or /usr/local/lib), then on Linux the environment variable LD_LIBRARY_PATH, and on Mac DYLD_LIBRARY_PATH, should include the paths to those dynamic libraries and must be set externally to MATLAB before it is started. On Windows, GTSAM and Boost library locations must be added to the PATH environment variable, unless GTSAM was built against static Boost libraries, in which case the static libraries are linked into a self-contained mex module with no dynamic library dependencies.
  5. Install GTSAM (with 'make install' on Linux or Mac or by building the INSTALL project on Windows), and the MATLAB wrapper will be compiled and installed as well.
  6. Add the installed MATLAB wrapper location to your MATLAB path.

Tested Systems:

In general any Unix-like (Mac, Linux, etc) or Windows system is expected to work.  The following have been tested:

  • Boost 1.43 or later is required to compile from source.  This does not apply to pre-compiled MATLAB wrapper. (see known issues below for Boost 1.58 support)
  • Ubuntu 12.04 and later - older Ubuntu versions require manually downloading and compiling Boost >= 1.43.
  • Debian - may require manually downloading and compiling Boost >= 1.43.
  • Mac OS 10.6-10.10 with Boost from MacPorts - Xcode 5 and 6. 
  • Windows 7 and 8-8.1 with Visual Studio 2010, 2012 and 2013 and CMake-generated solution files.

Known Issues:

These are some known issues specific to the 3.2.1 release:

  • Boost 1.58: This came out after GTSAM 3.2.1, and is not supported. The latest development code does support Boost 1.58 on Linux/Mac. Windows support is coming soon.
  • Windows: Visual Studio 2013 is only supported with Boost 1.56-1.57. Visual Studio 2013 must be fully up-to-date (update 4). Examples will not link properly if GTSAM is built statically, so a dynamic build is recommended. (This is the default.)
  • Linux: The Matlab toolbox cannot be compiled using gcc 4.8. gcc 4.7 or earlier work fine.
  • Mac OS: The Matlab toolbox must be built with serialization support disabled (in CMake.)