From 05dafa2334313c71eda55d2cae1ad931b377be37 Mon Sep 17 00:00:00 2001 From: Duy-Nguyen Ta Date: Fri, 25 Nov 2016 03:38:00 -0500 Subject: [PATCH] update and rename TODO to README. Add basic installation and usage instructions. --- cython/README.md | 117 +++++++++++++++++++++++++++++++++++++++++++++++ cython/TODO.md | 53 --------------------- 2 files changed, 117 insertions(+), 53 deletions(-) create mode 100644 cython/README.md delete mode 100644 cython/TODO.md diff --git a/cython/README.md b/cython/README.md new file mode 100644 index 000000000..e1540471a --- /dev/null +++ b/cython/README.md @@ -0,0 +1,117 @@ +This is the Cython/Python wrapper around the GTSAM C++ library. + +INSTALL +======= +- This wrapper needs Cython(>=0.25), numpy and eigency, which can be installed +as follows: + +>> cd /cython +>> pip install -r requirements.txt +>> pip install eigency + +Note: Currently there's some issue with including eigency in requirements.txt + +- Build and install gtsam using cmake with GTSAM\_INSTALL\_CYTHON_TOOLBOX enabled +Note: By default, the wrapped module will be installed in +/gtsam\_cython. Change that in GTSAM\_CYTHON\_TOOLBOX\_PATH + + +UNIT TESTS +========== +The Cython toolbox also has a small set of unit tests located in the +test directory. To run them: + +>> cd /Users/yourname/gtsam_cython # Change to wherever you installed the toolbox +>> python -m unittest discover + + +WRITING YOUR OWN SCRIPTS +======================== +See the tests for examples. + +## Some important notes: + +- Vector/Matrix: Due to a design choice of eigency, numpy.array matrices with the default order='A' +will always be transposed in C++ no matter how you transpose it in Python. Use order='F', or use +two functions Vector and Matrix in gtsam\_utils/np\_utils.py for your conveniences. These two functions +also help to avoid a common but very subtle bug of using integers when creating numpy arrays, +e.g. np.array([1,2,3]). These can't be an input for gtsam functions as they only accept floating-point arrays. +For more details, see: https://github.com/wouterboomsma/eigency#storage-layout---why-arrays-are-sometimes-transposed + +- Inner namespace: Classes in inner namespace will be prefixed by _ in Python. +Examples: noiseModel\_Gaussian, noiseModeli\_mEstimator\_Tukey + +- Use keyword arguments to differentiate overloads with the same number of arguments. +This applies for all constructors, methods and static methods. +Now the variable names become important in these cases!!! +Examples: Pose3(t=Matrix([...])), Pose3(pose2=Pose2()), Pose3(other=Pose3()) +Pose2(v=Vector([1,2,3])), Pose2(other=otherPose2) + +- Values::insert and update are now templated functions. Their python versions have the corresponding instantiated types added. +Examples: values.insertPose3(1, Pose3()), values.insertRot3(2, Rot3()), values.insertimuBias_ConstantBias(3, bias) + +- Casting from a base class to a derive class must be done explicitly. +Examples: + noiseBase = factor.get\_noiseModel() + noiseGaussian = dynamic\_cast\_noiseModel\_Gaussian\_noiseModel\_Base(noiseBase) + + + +KNOWN ISSUES +============ + - Doesn't work with python3 installed from homebrew + - size-related issue: can only wrap up to a certain number of classes: up to mEstimator! + - Guess: 64 vs 32b? disutils Compiler flags? + - Bug with Cython 0.24: instantiated factor classes return FastVector for keys(), which can't be casted to FastVector + - Upgrading to 0.25 solves the problem + - Need default constructor and default copy constructor for almost every classes... :( + - support these constructors by default and declare "delete" for special classes? + + +TODO +===== +☐ Unify cython/gtsam.h and the original gtsam.h + - 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, + to FastVector. + +Completed/Cancelled: +✔ 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 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) + +- 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/cython/TODO.md b/cython/TODO.md deleted file mode 100644 index 147ddd70e..000000000 --- a/cython/TODO.md +++ /dev/null @@ -1,53 +0,0 @@ - -TODO: -☐ [REFACTOR] better name for uninstantiateClass: very vague!! -☐ Unify cython/gtsam.h and the original gtsam.h -☐ CMake install script - -Completed/Cancelled: -✘ 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 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) - - -- inference before symbolic/linear -- what's the purpose of "virtual" ?? -- Need default constructor and default copy constructor for almost every classes... :( - ☐ support these constructors by default and declare "delete" for special classes? - -Installation: - ☐ Prerequisite: - - Users create venv and pip install requirements before compiling - - Wrap cython script in gtsam/cython folder - ☐ Install built module into venv? - -Known issues: - ☐ Doesn't work with python3 installed from homebrew - - size-related issue: can only wrap up to a certain number of classes: up to mEstimator! - - Guess: 64 vs 32b? disutils Compiler flags? - ☐ Bug with Cython 0.24: instantiated factor classes return FastVector for keys(), which can't be casted to FastVector - - Upgrading to 0.25 solves the problem