README

Python Wrapper

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

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 Cython(>=0.25.2), backports_abc(>=0.5), and numpy(>=1.11.0). These can be installed as follows:
```
pip install -r <gtsam_folder>/cython/requirements.txt
```
For compatibility with GTSAM's Eigen version, it contains its own cloned version of Eigency, named gtsam_eigency, to interface between C++'s Eigen and Python's numpy.

Run cmake with the GTSAM_INSTALL_CYTHON_TOOLBOX cmake flag enabled to configure building the wrapper. The wrapped module will be built and copied to the directory defined by GTSAM_CYTHON_INSTALL_PATH, which is by default <PROJECT_BINARY_DIR>/cython in Release mode and <PROJECT_BINARY_DIR>/cython<CMAKE_BUILD_TYPE> for other modes.
Build GTSAM and the wrapper with make.
To install, simply run make 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.

The Cython toolbox also has a small set of unit tests located in the test directory. To run them:

cd <GTSAM_CYTHON_INSTALL_PATH>
python -m unittest discover

TODO

TODO

See the tests for examples.

Vector/Matrix:
- GTSAM expects double-precision floating point vectors and matrices. Hence, you should pass numpy matrices with dtype=float, or float64.
- Also, GTSAM expects column-major matrices, unlike the default storage scheme in numpy. Hence, you should pass column-major matrices to GTSAM using the flag order='F'. And you always get column-major matrices back. For more details, see this link.
- Passing row-major matrices of different dtype, e.g. int, will also work as the wrapper converts them to column-major and dtype float for you, using numpy.array.astype(float, order='F', copy=False). However, this will result a copy if your matrix is not in the expected type and storage order.
Inner namespace: Classes in inner namespace will be prefixed by _ in Python.

Examples: noiseModel_Gaussian, noiseModel_mEstimator_Tukey

Casting from a base class to a derive class must be done explicitly.

Examples:

noiseBase = factor.noiseModel()
noiseGaussian = dynamic_cast_noiseModel_Gaussian_noiseModel_Base(noiseBase)

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