Merge pull request #67 from borglab/feature/housekeeping

Housekeeping

.github/ISSUE_TEMPLATE/bug-report.md

@@ -0,0 +1,35 @@
+---
+name: "Bug Report"
+about: Submit a bug report to help us improve GTSAM
+---
+
+<!--Please only submit issues/bug reports that come with enough information to reproduce them, ideally a unit test that fails, and possible ideas on what might be wrong. -->
+
+<!-- Even better yet, fix the bug and/or documentation, add a unit test, and create a pull request! -->
+
+<!-- This is a channel to report bugs/issues, not a support channel to help install/use/debug your own code. We'd love to help, but just don't have the bandwidth. Please post questions in the GTSAM Google group (https://groups.google.com/forum/#!forum/gtsam-users) -->
+
+## Description
+
+<!-- A clear description of the bug -->
+
+## Steps to reproduce
+
+1. 
+2.
+
+<!-- If you have a code sample, unit test, error messages, stack traces, etc., please provide it here as well -->
+
+## Expected behavior
+
+<!-- A clear and concise description of what you expected to happen. -->
+
+## Environment
+
+<!-- Please provide information about your code environment, things such as OS, language of use (C++, Matlab or Python), version of dependent libraries if using a custom build etc., anything to provide us more information. -->
+
+<!-- The more the information, the faster we can help resolve the issue -->
+
+## Additional information
+
+<!-- Add any other infor or context about the problem here. -->

.github/ISSUE_TEMPLATE/feature-request.md

@@ -0,0 +1,24 @@
+---
+name: "Feature Request"
+about: Submit a proposal/request for a new GTSAM feature
+---
+
+## Feature
+
+<!-- A clear and concise description of the feature proposal -->
+
+## Motivation
+
+<!-- Please outline the motivation for the proposal. Is your feature request related to a problem? e.g., I'm always frustrated when [...]. If this is related to another GitHub issue, please link here too. -->
+
+## Pitch
+
+<!-- A clear and concise description of what you want to happen. -->
+
+## Alternatives
+
+<!-- A clear and concise description of any alternative solutions or features you've considered, if any. -->
+
+## Additional context
+
+<!-- Add any other context or screenshots about the feature request here. -->

.github/ISSUE_TEMPLATE/questions-help-support.md

@@ -0,0 +1,5 @@
+---
+name: "Questions/Help/Support"
+---
+
+Please post questions and support requests in the [GTSAM Google group](https://groups.google.com/forum/#!forum/gtsam-users) and not on Github.

DEVELOP

@@ -1,19 +0,0 @@
-Information for developers
-
-Coding Conventions:
-
-* Classes are Uppercase, methods and functions lowerMixedCase
-* We use a modified K&R Style, with 2-space tabs, inserting spaces for tabs
-* Use meaningful variable names, e.g., measurement not msm
-
-
-Windows:
-
-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.
-
-For example:
-class GTSAM_EXPORT MyClass { ... };
-
-GTSAM_EXPORT myFunction();

DEVELOP.md

@@ -0,0 +1,19 @@
+# Information for Developers
+
+### Coding Conventions
+
+* Classes are Uppercase, methods and functions lowerMixedCase.
+* We use a modified K&R Style, with 2-space tabs, inserting spaces for tabs.
+* Use meaningful variable names, e.g. `measurement` not `msm`.
+
+
+### Windows
+
+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.
+
+For example:
+```cpp
+class GTSAM_EXPORT MyClass { ... };
+
+GTSAM_EXPORT myFunction();
+```

USAGE.md

@@ -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
 
-Getting Started
+### Install
----------------------------------------------------
-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:
+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.
-  	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 
+### Compiling/Linking with GTSAM
-  	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`.  
 
-Overview
+### Examples
----------------------------------------------------
+
-The GTSAM library has three primary components necessary for the construction
+To see how the library works, examine the unit tests provided.  
-of factor graph representation and optimization which users will need to 
+ 
-adapt to their particular problem.  
+## 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.  
+
+* FactorGraph
 
-* 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:
+	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.
 
 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
     geometry      points, poses, tensors, etc
     inference     core graphical model inference such as factor graphs, junction trees, Bayes nets, Bayes trees 

bitbucket-pipelines.yml

@@ -1,15 +0,0 @@
-# Built from sample configuration for C++ – Make.
-# Check https://confluence.atlassian.com/x/5Q4SMw for more examples.
-# -----
-# Our custom docker image from Docker Hub as the build environment.
-image: dellaert/ubuntu-boost-tbb-eigen3:bionic
-
-pipelines:
-  default:
-    - step:
-        script: # Modify the commands below to build your repository.
-          - mkdir build
-          - cd build
-          - cmake -DGTSAM_USE_SYSTEM_EIGEN=OFF -DGTSAM_USE_EIGEN_MKL=OFF .. 
-          - make -j2
-          - make -j2 check

cmake/README.md

@@ -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:
 
@@ -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.
 
-GtsamBuildTypes
+## GtsamBuildTypes
----------------
 
     include(GtsamBuildTypes)
 
@@ -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_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)
 
@@ -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.
         linkLibraries: The list of libraries to link to.
 
-GtsamMatlabWrap
+## 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
                           the wrap code.  Normally, leave this empty.
 
-GtsamMakeConfigFile
+## GtsamMakeConfigFile
--------------------
 
     include(GtsamMakeConfigFile)
      

cython/README.md

@@ -1,7 +1,7 @@
 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 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:
@@ -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`.
       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
 test directory. To run them:
 
@@ -37,8 +37,8 @@ test directory. To run them:
  python -m unittest discover
 ```
 
-WRITING YOUR OWN SCRIPTS
+# WRITING YOUR OWN SCRIPTS
-========================
+
 See the tests for examples.
 
 ## Some important notes:
@@ -66,8 +66,8 @@ Examples:
       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}
   + 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?
 
 
-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
 - 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?

gtsam/base/cholesky.cpp

@@ -111,7 +111,7 @@ bool choleskyPartial(Matrix& ABC, size_t nFrontal, size_t topleft) {
     return true;
 
   assert(ABC.cols() == ABC.rows());
-  assert(ABC.rows() >= topleft);
+  assert(size_t(ABC.rows()) >= topleft);
   const size_t n = static_cast<size_t>(ABC.rows() - topleft);
   assert(nFrontal <= size_t(n));
 

gtsam/linear/HessianFactor.cpp

@@ -505,7 +505,7 @@ VectorValues HessianFactor::solve() {
 
   // Do Cholesky Factorization
   const size_t n = size();
-  assert(info_.nBlocks() == n + 1);
+  assert(size_t(info_.nBlocks()) == n + 1);
   info_.choleskyPartial(n);
   auto R = info_.triangularView(0, n);
   auto eta = linearTerm();

wrap/README.md

@@ -1,25 +1,21 @@
-Frank Dellaert
+# WRAP README
-October 2011
 
 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:
 
 OBJECT CREATION
+
 - Classes are created by special constructors, e.g., new_GaussianFactorGraph_.cpp.
 	These constructors are called from the MATLAB class @GaussianFactorGraph.
 	new_GaussianFactorGraph_ calls wrap_constructed in matlab.h, see documentation there
 	
 METHOD (AND CONSTRUCTOR) ARGUMENTS
+
 - Simple argument types of methods, such as "double", will be converted in the
   mex wrappers by calling unwrap<double>, defined in matlab.h
 - Vector and Matrix arguments are normally passed by reference in GTSAM, but