renamed all READMEs to README.md and updated markdown syntax

borglab · Jun 13, 2019 · b829239 · b829239
1 parent e72b42b
commit b829239
Show file tree

Hide file tree

Showing 6 changed files with 110 additions and 133 deletions.
diff --git a/DEVELOP.md b/DEVELOP.md
@@ -1,19 +1,19 @@
-Information for developers
+# Information for Developers
 
-Coding Conventions:
+### 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
+* 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:
+### 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.
+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();
+GTSAM_EXPORT myFunction();
+```
diff --git a/USAGE.md b/USAGE.md
@@ -1,48 +1,42 @@
-USAGE - Georgia Tech Smoothing and Mapping library
-===================================
-What is this file?
+# GTSAM USAGE
 
-	This file explains how to make use of the library for common SLAM tasks, 
-	using a visual SLAM implementation as an example.
-
+This file explains how to make use of the library for common SLAM tasks, using a visual SLAM implementation as an example.
+
+## Getting Started
+
+### Install
 
-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:
-  	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:
-	To see how the library works, examine the unit tests provided.  
+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
+
+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
+
+To see how the library works, examine the unit tests provided.  
 
+## 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
+
+	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
 
-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:
-	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.
 
 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 

diff --git a/cmake/README.md b/cmake/README.md
@@ -1,14 +1,12 @@
-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:
 
     find_package(GTSAMCMakeTools)
 
 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)
 
@@ -17,8 +15,8 @@ Including this file immediately sets up the following build types and a drop-dow
 *   `Debug`
 *   `Release`
 *   `RelWithDebInfo`
-*   `Profiling`:  All optimizations enabled and minimal debug symbols
-*   `Timing`:  Defines the symbol GTSAM_ENABLE_TIMING for using GTSAM timing instrumentation
+*   `Profiling`: All optimizations enabled and minimal debug symbols
+*   `Timing`: Defines the symbol GTSAM_ENABLE_TIMING for using GTSAM timing instrumentation
 
 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_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)
      

diff --git a/cython/README.md b/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
-=====
-☐ 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?)
-☐ inner namespaces ==> inner packages?
-☐ Wrap fixed-size Matrices/Vectors?
-
-
-Completed/Cancelled:
-=====
-✔ Fix Python tests: don't use " import <package> * ": Bad style!!! @done (18-03-17 19:50)
-✔ Unit tests for cython wrappers @done (18-03-17 18:45) -- simply compare generated files
-✔ Wrap unstable @done (18-03-17 15:30)
-✔ 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.
-  ✔ 06-03-17: manage to remove the requirements for default and copy constructors
-  ✘ 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>.
-✘ 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.
-✔ Convert input numpy Matrix/Vector to float dtype and storage order 'F' automatically, cannot crash! @done (15-03-17 13:00)
-✔ Remove requirements.txt - Frank: don't bother with only 2 packages and a special case for eigency! @done (08-03-17 10:30)
-✔ CMake install script @done (25-11-16 02:30)
-✘ [REFACTOR] better name for uninstantiateClass: very vague!! @cancelled (25-11-16 02:30) -- lazy
-✘ forward declaration? @cancelled (23-11-16 13:00) - nothing to do, seem to work?
-✔ wrap VariableIndex: why is it in inference? If need to, shouldn't have constructors to specific FactorGraphs @done (23-11-16 13:00)
-✔ Global functions @done (22-11-16 21:00)
-✔ [REFACTOR] typesEqual --> isSameSignature @done (22-11-16 21:00)
-✔ Proper overloads (constructors, static methods, methods) @done (20-11-16 21:00)
-✔ Allow overloading methods. The current solution is annoying!!! @done (20-11-16 21:00)
-✔ Casting from parent and grandparents @done (16-11-16 17:00)
-✔ Allow overloading constructors. The current solution is annoying!!! @done (16-11-16 17:00)
-✔ Support "print obj" @done (16-11-16 17:00)
-✔ methods for FastVector: at, [], ...  @done (16-11-16 17:00)
-✔ Cython: Key and size_t: traits<size_t> doesn't exist @done (16-09-12 18:34)
-✔ KeyVector, KeyList, KeySet... @done (16-09-13 17:19)
-✔ [Nice to have] parse typedef @done (16-09-13 17:19)
-✔ ctypedef at correct places @done (16-09-12 18:34)
-✔ expand template variable type in constructor/static methods? @done (16-09-12 18:34)
-✔ NonlinearOptimizer: copy constructor deleted!!! @done (16-09-13 17:20)
-✔ Value: no default constructor @done (16-09-13 17:20)
-✔ ctypedef PriorFactor[Vector] PriorFactorVector @done (16-09-19 12:25)
-✔ Delete duplicate methods in derived class @done (16-09-12 13:38)
-✔ Fix return properly @done (16-09-11 17:14)
- ✔ handle pair @done (16-09-11 17:14)
-✔ Eigency: ambiguous call: A(const T&) A(const Vector& v) and Eigency A(Map[Vector]& v) @done (16-09-11 07:59)
-✔ Eigency: Constructor: ambiguous construct from Vector/Matrix @done (16-09-11 07:59)
-✔ Eigency: Fix method template of Vector/Matrix: template argument is [Vector] while arugment is Map[Vector] @done (16-09-11 08:22)
-✔ Robust noise: copy assignment operator is deleted because of shared_ptr of the abstract Base class @done (16-09-10 09:05)
-✘ 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)
+# TODO
+
+- [ ] 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?)
+- [ ] inner namespaces ==> inner packages?
+- [ ] Wrap fixed-size Matrices/Vectors?
+
+
+# Completed/Cancelled:
+
+- [x] Fix Python tests: don't use " import <package> * ": Bad style!!! (18-03-17 19:50)
+- [x] Unit tests for cython wrappers @done (18-03-17 18:45) -- simply compare generated files
+- [x] Wrap unstable @done (18-03-17 15:30)
+- [x] Unify cython/gtsam.h and the original gtsam.h @done (18-03-17 15:30)
+- [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.
+- [x] 06-03-17: manage to remove the requirements for default and copy constructors
+- [ ] 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>.
+- [ ] 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] Convert input numpy Matrix/Vector to float dtype and storage order 'F' automatically, cannot crash! @done (15-03-17 13:00)
+- [x] Remove requirements.txt - Frank: don't bother with only 2 packages and a special case for eigency! @done (08-03-17 10:30)
+- [x] CMake install script @done (25-11-16 02:30)
+- [ ] [REFACTOR] better name for uninstantiateClass: very vague!! @cancelled (25-11-16 02:30) -- lazy
+- [ ] forward declaration? @cancelled (23-11-16 13:00) - nothing to do, seem to work?
+- [x] wrap VariableIndex: why is it in inference? If need to, shouldn't have constructors to specific FactorGraphs @done (23-11-16 13:00)
+- [x] Global functions @done (22-11-16 21:00)
+- [x] [REFACTOR] typesEqual --> isSameSignature @done (22-11-16 21:00)
+- [x] Proper overloads (constructors, static methods, methods) @done (20-11-16 21:00)
+- [x] Allow overloading methods. The current solution is annoying!!! @done (20-11-16 21:00)
+- [x] Casting from parent and grandparents @done (16-11-16 17:00)
+- [x] Allow overloading constructors. The current solution is annoying!!! @done (16-11-16 17:00)
+- [x] Support "print obj" @done (16-11-16 17:00)
+- [x] methods for FastVector: at, [], ...  @done (16-11-16 17:00)
+- [x] Cython: Key and size_t: traits<size_t> doesn't exist @done (16-09-12 18:34)
+- [x] KeyVector, KeyList, KeySet... @done (16-09-13 17:19)
+- [x] [Nice to have] parse typedef @done (16-09-13 17:19)
+- [x] ctypedef at correct places @done (16-09-12 18:34)
+- [x] expand template variable type in constructor/static methods? @done (16-09-12 18:34)
+- [x] NonlinearOptimizer: copy constructor deleted!!! @done (16-09-13 17:20)
+- [x] Value: no default constructor @done (16-09-13 17:20)
+- [x] ctypedef PriorFactor[Vector] PriorFactorVector @done (16-09-19 12:25)
+- [x] Delete duplicate methods in derived class @done (16-09-12 13:38)
+- [x] Fix return properly @done (16-09-11 17:14)
+- [x] handle pair @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)
+- [x] Eigency: Constructor: ambiguous construct from Vector/Matrix @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)
+- [x] Robust noise: copy assignment operator is deleted because of shared_ptr of the abstract Base class @done (16-09-10 09:05)
+- [ ] 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?
diff --git a/gtsam_unstable/examples/README → gtsam_unstable/examples/README.md b/gtsam_unstable/examples/README → gtsam_unstable/examples/README.md
diff --git a/wrap/README → wrap/README.md b/wrap/README → wrap/README.md
@@ -1,25 +1,21 @@
-Frank Dellaert
-October 2011
+# WRAP README
 
 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 
-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.  
+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.  
 
-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
+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
 
 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