diff --git a/README.md b/README.md new file mode 100644 index 000000000..1f55b88d1 --- /dev/null +++ b/README.md @@ -0,0 +1,186 @@ +README - Georgia Tech Smoothing and Mapping library +=================================================== + +Quickstart + +In the root library folder execute: + +``` +#!bash +$ mkdir build +$ cd build +$ cmake .. +$ make!check (optional, runs unit tests) +$ make install +``` + +See INSTALL for more detailed installation instructions. + +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 the `examples/` directory and the USAGE file for examples 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 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.2: General C++ matrix and linear algebra library + - Licenced under MPL2, provided in gtsam/3rdparty/Eigen/COPYING.README (some code that is 3rd-party to + Eigen is BSD and 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 + +Optional dependent libraries: + - If TBB is installed and detectable by CMake GTSAM will use it automatically. + Ensure that CMake prints "Use Intel TBB : Yes". To disable the use of TBB, + disable the CMake flag GTSAM_WITH_TBB (enabled by default). On Ubuntu, TBB + may be installed from the Ubuntu repositories, and for other platforms it + may be downloaded from https://www.threadingbuildingblocks.org/ + +Tested compilers + - GCC 4.2-4.7 + - Clang 2.9-3.2 + - OSX GCC 4.2 + - MSVC 2010, 2012 + +Tested systems: + - Ubuntu 11.04, 11.10, 12.04, 12.10, 13.04 + - MacOS 10.6, 10.7 + - Windows 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 'make doc' from your +build directory. + +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". + +MEX_COMMAND: Path to the mex compiler. Defaults to assume the path is included in your +shell's PATH environment variable. mex is installed with matlab at +$MATLABROOT/bin/mex + +$MATLABROOT can be found by executing the command 'matlabroot' in MATLAB + +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.