Skip to content

Latest commit

 

History

History
67 lines (44 loc) · 3.04 KB

README.md

File metadata and controls

67 lines (44 loc) · 3.04 KB
Raw

README

Python Wrapper

This is the Python wrapper around the GTSAM C++ library. We use our custom wrap library to generate the bindings to the underlying C++ code.

For instructions on updating the version of the wrap library included in GTSAM to the latest version, please refer to the wrap README

Requirements

  • Cmake >= 3.15

  • If you want to build the GTSAM python library for a specific python version (eg 3.6), use the -DGTSAM_PYTHON_VERSION=3.6 option when running cmake otherwise the default interpreter will be used.

  • If the interpreter is inside an environment (such as an anaconda environment or virtualenv environment), then the environment should be active while building GTSAM.

  • This wrapper needs pyparsing(>=2.4.2), pybind-stubgen>=2.5.1 and numpy(>=1.11.0). These can all be installed as follows:

    pip install -r <gtsam_folder>/python/dev_requirements.txt

Install

  • Run cmake with the GTSAM_BUILD_PYTHON cmake flag enabled to configure building the wrapper. The wrapped module will be built and copied to the directory <PROJECT_BINARY_DIR>/python. For example, if your local Python version is 3.6.10, then you should run:

    cmake .. -DGTSAM_BUILD_PYTHON=1 -DGTSAM_PYTHON_VERSION=3.6.10

    If you do not have TBB installed, you should also provide the argument -DGTSAM_WITH_TBB=OFF.

  • Build GTSAM and the wrapper with make (or ninja if you use -GNinja).

  • To install, simply run make python-install (ninja python-install).

    • The same command can be used to install into a virtual environment if it is active.
    • NOTE: if you don't want GTSAM to install to a system directory such as /usr/local, pass -DCMAKE_INSTALL_PREFIX="./install" to cmake to install GTSAM to a subdirectory of the build directory.

  • You can also directly run make python-install without running make, and it will compile all the dependencies accordingly.

Unit Tests

The Python toolbox also has a small set of unit tests located in the test directory. To run them, use make python-test.

Utils

TODO

Examples

TODO

Writing Your Own Scripts

See the tests for examples.

Some Important Notes:

  • Vector/Matrix:

    • GTSAM expects double-precision floating point vectors and matrices. Hence, you should pass numpy matrices with dtype=float, or float64, to avoid any conversion needed.
    • Also, GTSAM expects column-major matrices, unlike the default storage scheme in numpy. But this is only performance-related as pybind11 should translate them when needed. However, this will result a copy if your matrix is not in the expected type and storage order.

Wrapping Custom GTSAM-based Project

Please refer to the template project and the corresponding tutorial available here.