12345qiupeng
/
gtsam
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

renamed all READMEs to README.md and updated markdown syntax

release/4.3a0
Varun Agrawal 2019-06-13 17:26:07 -04:00
parent e72b42b614
commit b8292399d6
6 changed files with 105 additions and 128 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
DEVELOP.md
View File

@ -1,19 +1,19 @@
Information for developers # Information for Developers
Coding Conventions: ### Coding Conventions
* Classes are Uppercase, methods and functions lowerMixedCase * Classes are Uppercase, methods and functions lowerMixedCase.
* We use a modified K&R Style, with 2-space tabs, inserting spaces for tabs * We use a modified K&R Style, with 2-space tabs, inserting spaces for tabs.
* Use meaningful variable names, e.g., measurement not msm * Use meaningful variable names, e.g. `measurement` not `msm`.
Windows: ### Windows
On Windows it is necessary to explicitly export all functions from the library On Windows it is necessary to explicitly export all functions from the library which should be externally accessible. To do this, include the macro `GTSAM_EXPORT` in your class or function definition.
which should be externally accessible. To do this, include the macro
GTSAM_EXPORT in your class or function definition.
For example: For example:
```cpp
class GTSAM_EXPORT MyClass { ... }; class GTSAM_EXPORT MyClass { ... };
GTSAM_EXPORT myFunction(); GTSAM_EXPORT myFunction();
```

62
USAGE.md
View File

@ -1,48 +1,42 @@
USAGE - Georgia Tech Smoothing and Mapping library # GTSAM USAGE
===================================
What is this file?
This file explains how to make use of the library for common SLAM tasks, This file explains how to make use of the library for common SLAM tasks, using a visual SLAM implementation as an example.
using a visual SLAM implementation as an example.
## Getting Started
### Install
Follow the installation instructions in the README file to build and install gtsam, as well as running tests to ensure the library is working properly.
Getting Started
---------------------------------------------------
Install:
Follow the installation instructions in the README file to build and
install gtsam, as well as running tests to ensure the library is working
properly.
Compiling/Linking with gtsam: ### Compiling/Linking with GTSAM
The installation creates a binary "libgtsam" at the installation prefix,
and an include folder "gtsam". These are the only required includes, but
the library has also been designed to make use of XML serialization through
the Boost.serialization library, which requires the the Boost.serialization
headers and binaries to be linked.
If you use CMake for your project, you can use the CMake scripts in the
cmake folder for finding GTSAM, CppUnitLite, and Wrap.
Examples: The installation creates a binary `libgtsam` at the installation prefix, and an include folder `gtsam`. These are the only required includes, but the library has also been designed to make use of XML serialization through the `Boost.serialization` library, which requires the the Boost.serialization headers and binaries to be linked.
To see how the library works, examine the unit tests provided.
If you use CMake for your project, you can use the CMake scripts in the cmake folder for finding `GTSAM`, `CppUnitLite`, and `Wrap`.
### Examples
To see how the library works, examine the unit tests provided.
## Overview
Overview The GTSAM library has three primary components necessary for the construction of factor graph representation and optimization which users will need to adapt to their particular problem.
---------------------------------------------------
The GTSAM library has three primary components necessary for the construction * FactorGraph
of factor graph representation and optimization which users will need to
adapt to their particular problem. A factor graph contains a set of variables to solve for (i.e., robot poses, landmark poses, etc.) and a set of constraints between these variables, which make up factors.
* Values:
Values is a single object containing labeled values for all of the variables. Currently, all variables are labeled with strings, but the type or organization of the variables can change.
* Factors
* FactorGraph:
A factor graph contains a set of variables to solve for (i.e., robot poses, landmark poses, etc.) and a set of constraints between these variables, which make up factors.
* Values:
Values is a single object containing labeled values for all of the variables. Currently, all variables are labeled with strings, but the type or organization of the variables can change
* Factors:
A nonlinear factor expresses a constraint between variables, which in the SLAM example, is a measurement such as a visual reading on a landmark or odometry. A nonlinear factor expresses a constraint between variables, which in the SLAM example, is a measurement such as a visual reading on a landmark or odometry.
The library is organized according to the following directory structure: The library is organized according to the following directory structure:
3rdparty local copies of third party libraries - Eigen3 and CCOLAMD 3rdparty local copies of third party libraries e.g. Eigen3 and CCOLAMD
base provides some base Math and data structures, as well as test-related utilities base provides some base Math and data structures, as well as test-related utilities
geometry points, poses, tensors, etc geometry points, poses, tensors, etc
inference core graphical model inference such as factor graphs, junction trees, Bayes nets, Bayes trees inference core graphical model inference such as factor graphs, junction trees, Bayes nets, Bayes trees

19
cmake/README.md
View File

@ -1,5 +1,4 @@
GTSAMCMakeTools # GTSAMCMakeTools
===============
This is the collection of GTSAM CMake tools that may be useful in external projects. The way to use this collection is by first making a find_package call: This is the collection of GTSAM CMake tools that may be useful in external projects. The way to use this collection is by first making a find_package call:
@ -7,8 +6,7 @@ This is the collection of GTSAM CMake tools that may be useful in external proje
which will add a directory containing the GTSAM CMake tools to the CMAKE_MODULE_PATH variable. After that, you may include the files you would like to use. These files and the functions they define are explained below. which will add a directory containing the GTSAM CMake tools to the CMAKE_MODULE_PATH variable. After that, you may include the files you would like to use. These files and the functions they define are explained below.
GtsamBuildTypes ## GtsamBuildTypes
---------------
include(GtsamBuildTypes) include(GtsamBuildTypes)
@ -17,8 +15,8 @@ Including this file immediately sets up the following build types and a drop-dow
* `Debug` * `Debug`
* `Release` * `Release`
* `RelWithDebInfo` * `RelWithDebInfo`
* `Profiling`: All optimizations enabled and minimal debug symbols * `Profiling`: All optimizations enabled and minimal debug symbols
* `Timing`: Defines the symbol GTSAM_ENABLE_TIMING for using GTSAM timing instrumentation * `Timing`: Defines the symbol GTSAM_ENABLE_TIMING for using GTSAM timing instrumentation
It also configures several minor details, as follows: It also configures several minor details, as follows:
@ -30,8 +28,7 @@ It defines the following functions:
* `gtsam_assign_source_folders( [files] )` Organizes files in the IDE into folders to reflect the actual directory structure of those files. Folders will be determined relative to the current source folder when this function is called. * `gtsam_assign_source_folders( [files] )` Organizes files in the IDE into folders to reflect the actual directory structure of those files. Folders will be determined relative to the current source folder when this function is called.
* `gtsam_assign_all_source_folders()` Calls `gtsam_assign_source_folders` on all cpp, c, and h files recursively in the current source folder. * `gtsam_assign_all_source_folders()` Calls `gtsam_assign_source_folders` on all cpp, c, and h files recursively in the current source folder.
GtsamTesting ## GtsamTesting
------------
include(GtsamTesting) include(GtsamTesting)
@ -70,8 +67,7 @@ Defines two useful functions for creating CTest unit tests. Also immediately cr
an empty string "" if nothing needs to be excluded. an empty string "" if nothing needs to be excluded.
linkLibraries: The list of libraries to link to. linkLibraries: The list of libraries to link to.
GtsamMatlabWrap ## GtsamMatlabWrap
---------------
include(GtsamMatlabWrap) include(GtsamMatlabWrap)
@ -97,8 +93,7 @@ Defines functions for generating MATLAB wrappers. Also immediately creates seve
extraMexFlags: Any *additional* flags to pass to the compiler when building extraMexFlags: Any *additional* flags to pass to the compiler when building
the wrap code. Normally, leave this empty. the wrap code. Normally, leave this empty.
GtsamMakeConfigFile ## GtsamMakeConfigFile
-------------------
include(GtsamMakeConfigFile) include(GtsamMakeConfigFile)

118
cython/README.md
View File

@ -1,7 +1,7 @@
This is the Cython/Python wrapper around the GTSAM C++ library. This is the Cython/Python wrapper around the GTSAM C++ library.
INSTALL # INSTALL
=======
- if you want to build the gtsam python library for a specific python version (eg 2.7), use the `-DGTSAM_PYTHON_VERSION=2.7` option when running `cmake` otherwise the default interpreter will be used. - if you want to build the gtsam python library for a specific python version (eg 2.7), use the `-DGTSAM_PYTHON_VERSION=2.7` 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. - 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. These can be installed as follows: - This wrapper needs Cython(>=0.25.2), backports_abc>=0.5, and numpy. These can be installed as follows:
@ -27,8 +27,8 @@ export PYTHONPATH=$PYTHONPATH:<GTSAM_CYTHON_INSTALL_PATH>
- if you run `setup.py` from the build directory rather than the installation directory, the script will warn you with the message: `setup.py is being run from an unexpected location`. - if you run `setup.py` from the build directory rather than the installation directory, the script will warn you with the message: `setup.py is being run from an unexpected location`.
Before `make install` is run, not all the components of the package have been copied across, so running `setup.py` from the build directory would result in an incomplete package. Before `make install` is run, not all the components of the package have been copied across, so running `setup.py` from the build directory would result in an incomplete package.
UNIT TESTS # UNIT TESTS
==========
The Cython toolbox also has a small set of unit tests located in the The Cython toolbox also has a small set of unit tests located in the
test directory. To run them: test directory. To run them:
@ -37,8 +37,8 @@ test directory. To run them:
python -m unittest discover python -m unittest discover
``` ```
WRITING YOUR OWN SCRIPTS # WRITING YOUR OWN SCRIPTS
========================
See the tests for examples. See the tests for examples.
## Some important notes: ## Some important notes:
@ -66,8 +66,8 @@ Examples:
noiseGaussian = dynamic_cast_noiseModel_Gaussian_noiseModel_Base(noiseBase) noiseGaussian = dynamic_cast_noiseModel_Gaussian_noiseModel_Base(noiseBase)
``` ```
WRAPPING YOUR OWN PROJECT THAT USES GTSAM # WRAPPING YOUR OWN PROJECT THAT USES GTSAM
=========================================
- Set PYTHONPATH to include ${GTSAM_CYTHON_INSTALL_PATH} - Set PYTHONPATH to include ${GTSAM_CYTHON_INSTALL_PATH}
+ so that it can find gtsam Cython header: gtsam/gtsam.pxd + so that it can find gtsam Cython header: gtsam/gtsam.pxd
@ -99,63 +99,55 @@ KNOWN ISSUES
- support these constructors by default and declare "delete" for special classes? - support these constructors by default and declare "delete" for special classes?
TODO # TODO
=====
☐ allow duplication of parent' functions in child classes. Not allowed for now due to conflicts in Cython. - [ ] allow duplication of parent' functions in child classes. Not allowed for now due to conflicts in Cython.
☐ a common header for boost shared_ptr? (Or wait until everything is switched to std::shared_ptr in gtsam?) - [ ] a common header for boost shared_ptr? (Or wait until everything is switched to std::shared_ptr in gtsam?)
☐ inner namespaces ==> inner packages? - [ ] inner namespaces ==> inner packages?
☐ Wrap fixed-size Matrices/Vectors? - [ ] Wrap fixed-size Matrices/Vectors?
Completed/Cancelled: # Completed/Cancelled:
=====
✔ Fix Python tests: don't use " import <package> * ": Bad style!!! @done (18-03-17 19:50) - [x] Fix Python tests: don't use " import <package> * ": Bad style!!! (18-03-17 19:50)
✔ Unit tests for cython wrappers @done (18-03-17 18:45) -- simply compare generated files - [x] Unit tests for cython wrappers @done (18-03-17 18:45) -- simply compare generated files
✔ Wrap unstable @done (18-03-17 15:30) - [x] Wrap unstable @done (18-03-17 15:30)
✔ Unify cython/gtsam.h and the original gtsam.h @done (18-03-17 15:30) - [x] Unify cython/gtsam.h and the original gtsam.h @done (18-03-17 15:30)
✔ 18-03-17: manage to unify the two versions by removing std container stubs from the matlab version,and keeping KeyList/KeyVector/KeySet as in the matlab version. Probably Cython 0.25 fixes the casting problem. - [x] 18-03-17: manage to unify the two versions by removing std container stubs from the matlab version,and keeping KeyList/KeyVector/KeySet as in the matlab version. Probably Cython 0.25 fixes the casting problem.
✔ 06-03-17: manage to remove the requirements for default and copy constructors - [x] 06-03-17: manage to remove the requirements for default and copy constructors
✘ 25-11-16: - [ ] 25-11-16: Try to unify but failed. Main reasons are: Key/size_t, std containers, KeyVector/KeyList/KeySet. Matlab doesn't need to know about Key, but I can't make Cython to ignore Key as it couldn't cast KeyVector, i.e. FastVector<Key>, to FastVector<size_t>.
Try to unify but failed. Main reasons are: Key/size_t, std containers, KeyVector/KeyList/KeySet. - [ ] Marginal and JointMarginal: revert changes @failed (17-03-17 11:00) -- Cython does need a default constructor! It produces cpp code like this: ```gtsam::JointMarginal __pyx_t_1;``` Users don't have to wrap this constructor, however.
Matlab doesn't need to know about Key, but I can't make Cython to ignore Key as it couldn't cast KeyVector, i.e. FastVector<Key>, to FastVector<size_t>. - [x] Convert input numpy Matrix/Vector to float dtype and storage order 'F' automatically, cannot crash! @done (15-03-17 13:00)
✘ Marginal and JointMarginal: revert changes @failed (17-03-17 11:00) -- Cython does need a default constructor! It produces cpp code like this: ```gtsam::JointMarginal __pyx_t_1;``` Users don't have to wrap this constructor, however. - [x] Remove requirements.txt - Frank: don't bother with only 2 packages and a special case for eigency! @done (08-03-17 10:30)
✔ Convert input numpy Matrix/Vector to float dtype and storage order 'F' automatically, cannot crash! @done (15-03-17 13:00) - [x] CMake install script @done (25-11-16 02:30)
✔ Remove requirements.txt - Frank: don't bother with only 2 packages and a special case for eigency! @done (08-03-17 10:30) - [ ] [REFACTOR] better name for uninstantiateClass: very vague!! @cancelled (25-11-16 02:30) -- lazy
✔ CMake install script @done (25-11-16 02:30) - [ ] forward declaration? @cancelled (23-11-16 13:00) - nothing to do, seem to work?
✘ [REFACTOR] better name for uninstantiateClass: very vague!! @cancelled (25-11-16 02:30) -- lazy - [x] wrap VariableIndex: why is it in inference? If need to, shouldn't have constructors to specific FactorGraphs @done (23-11-16 13:00)
✘ forward declaration? @cancelled (23-11-16 13:00) - nothing to do, seem to work? - [x] Global functions @done (22-11-16 21:00)
✔ wrap VariableIndex: why is it in inference? If need to, shouldn't have constructors to specific FactorGraphs @done (23-11-16 13:00) - [x] [REFACTOR] typesEqual --> isSameSignature @done (22-11-16 21:00)
✔ Global functions @done (22-11-16 21:00) - [x] Proper overloads (constructors, static methods, methods) @done (20-11-16 21:00)
✔ [REFACTOR] typesEqual --> isSameSignature @done (22-11-16 21:00) - [x] Allow overloading methods. The current solution is annoying!!! @done (20-11-16 21:00)
✔ Proper overloads (constructors, static methods, methods) @done (20-11-16 21:00) - [x] Casting from parent and grandparents @done (16-11-16 17:00)
✔ Allow overloading methods. The current solution is annoying!!! @done (20-11-16 21:00) - [x] Allow overloading constructors. The current solution is annoying!!! @done (16-11-16 17:00)
✔ Casting from parent and grandparents @done (16-11-16 17:00) - [x] Support "print obj" @done (16-11-16 17:00)
✔ Allow overloading constructors. The current solution is annoying!!! @done (16-11-16 17:00) - [x] methods for FastVector: at, [], ... @done (16-11-16 17:00)
✔ Support "print obj" @done (16-11-16 17:00) - [x] Cython: Key and size_t: traits<size_t> doesn't exist @done (16-09-12 18:34)
✔ methods for FastVector: at, [], ... @done (16-11-16 17:00) - [x] KeyVector, KeyList, KeySet... @done (16-09-13 17:19)
✔ Cython: Key and size_t: traits<size_t> doesn't exist @done (16-09-12 18:34) - [x] [Nice to have] parse typedef @done (16-09-13 17:19)
✔ KeyVector, KeyList, KeySet... @done (16-09-13 17:19) - [x] ctypedef at correct places @done (16-09-12 18:34)
✔ [Nice to have] parse typedef @done (16-09-13 17:19) - [x] expand template variable type in constructor/static methods? @done (16-09-12 18:34)
✔ ctypedef at correct places @done (16-09-12 18:34) - [x] NonlinearOptimizer: copy constructor deleted!!! @done (16-09-13 17:20)
✔ expand template variable type in constructor/static methods? @done (16-09-12 18:34) - [x] Value: no default constructor @done (16-09-13 17:20)
✔ NonlinearOptimizer: copy constructor deleted!!! @done (16-09-13 17:20) - [x] ctypedef PriorFactor[Vector] PriorFactorVector @done (16-09-19 12:25)
✔ Value: no default constructor @done (16-09-13 17:20) - [x] Delete duplicate methods in derived class @done (16-09-12 13:38)
✔ ctypedef PriorFactor[Vector] PriorFactorVector @done (16-09-19 12:25) - [x] Fix return properly @done (16-09-11 17:14)
✔ Delete duplicate methods in derived class @done (16-09-12 13:38) - [x] handle pair @done (16-09-11 17:14)
✔ Fix return properly @done (16-09-11 17:14) - [x] Eigency: ambiguous call: A(const T&) A(const Vector& v) and Eigency A(Map[Vector]& v) @done (16-09-11 07:59)
✔ handle pair @done (16-09-11 17:14) - [x] Eigency: Constructor: ambiguous construct from Vector/Matrix @done (16-09-11 07:59)
✔ Eigency: ambiguous call: A(const T&) A(const Vector& v) and Eigency A(Map[Vector]& v) @done (16-09-11 07:59) - [x] Eigency: Fix method template of Vector/Matrix: template argument is [Vector] while arugment is Map[Vector] @done (16-09-11 08:22)
✔ Eigency: Constructor: ambiguous construct from Vector/Matrix @done (16-09-11 07:59) - [x] Robust noise: copy assignment operator is deleted because of shared_ptr of the abstract Base class @done (16-09-10 09:05)
✔ Eigency: Fix method template of Vector/Matrix: template argument is [Vector] while arugment is Map[Vector] @done (16-09-11 08:22) - [ ] Cython: Constructor: generate default constructor? (hack: if it's serializable?) @cancelled (16-09-13 17:20)
✔ Robust noise: copy assignment operator is deleted because of shared_ptr of the abstract Base class @done (16-09-10 09:05) - [ ] Eigency: Map[] to Block @created(16-09-10 07:59) @cancelled (16-09-11 08:28)
✘ Cython: Constructor: generate default constructor? (hack: if it's serializable?) @cancelled (16-09-13 17:20)
✘ Eigency: Map[] to Block @created(16-09-10 07:59) @cancelled (16-09-11 08:28)
- inference before symbolic/linear - inference before symbolic/linear
- what's the purpose of "virtual" ?? - what's the purpose of "virtual" ??
Installation:
☐ Prerequisite:
- Users create venv and pip install requirements before compiling
- Wrap cython script in gtsam/cython folder
☐ Install built module into venv?

0
gtsam_unstable/examples/README → gtsam_unstable/examples/README.md
View File

14
wrap/README → wrap/README.md
View File

@ -1,25 +1,21 @@
Frank Dellaert # WRAP README
October 2011
The wrap library wraps the GTSAM library into a MATLAB toolbox. The wrap library wraps the GTSAM library into a MATLAB toolbox.
It was designed to be more general than just wrapping GTSAM, but a small amount of It was designed to be more general than just wrapping GTSAM, but a small amount of GTSAM specific code exists in matlab.h, the include file that is included by the mex files. The GTSAM-specific functionality consists primarily of handling of Eigen Matrix and Vector classes.
GTSAM specific code exists in matlab.h, the include file that is included by the
mex files. The GTSAM-specific functionality consists primarily of handling of
Eigen Matrix and Vector classes.
For notes on creating a wrap interface, see gtsam.h for what features can be For notes on creating a wrap interface, see gtsam.h for what features can be wrapped into a toolbox, as well as the current state of the toolbox for gtsam. For more technical details on the interface, please read comments in matlab.h
wrapped into a toolbox, as well as the current state of the toolbox for gtsam.
For more technical details on the interface, please read comments in matlab.h
Some good things to know: Some good things to know:
OBJECT CREATION OBJECT CREATION
- Classes are created by special constructors, e.g., new_GaussianFactorGraph_.cpp. - Classes are created by special constructors, e.g., new_GaussianFactorGraph_.cpp.
These constructors are called from the MATLAB class @GaussianFactorGraph. These constructors are called from the MATLAB class @GaussianFactorGraph.
new_GaussianFactorGraph_ calls wrap_constructed in matlab.h, see documentation there new_GaussianFactorGraph_ calls wrap_constructed in matlab.h, see documentation there
METHOD (AND CONSTRUCTOR) ARGUMENTS METHOD (AND CONSTRUCTOR) ARGUMENTS
- Simple argument types of methods, such as "double", will be converted in the - Simple argument types of methods, such as "double", will be converted in the
mex wrappers by calling unwrap<double>, defined in matlab.h mex wrappers by calling unwrap<double>, defined in matlab.h
- Vector and Matrix arguments are normally passed by reference in GTSAM, but - Vector and Matrix arguments are normally passed by reference in GTSAM, but