From 214b1208b1150ad43084cebec3234e6d08207bc7 Mon Sep 17 00:00:00 2001 From: Varun Agrawal Date: Wed, 20 Mar 2019 15:30:49 -0400 Subject: [PATCH 1/4] changed MATLAB README to markdown file for better rendering --- matlab/README-gtsam-toolbox.md | 57 +++++++++++++++++++++++ matlab/README-gtsam-toolbox.txt | 82 --------------------------------- 2 files changed, 57 insertions(+), 82 deletions(-) create mode 100644 matlab/README-gtsam-toolbox.md delete mode 100644 matlab/README-gtsam-toolbox.txt diff --git a/matlab/README-gtsam-toolbox.md b/matlab/README-gtsam-toolbox.md new file mode 100644 index 000000000..f23cf1da1 --- /dev/null +++ b/matlab/README-gtsam-toolbox.md @@ -0,0 +1,57 @@ +# GTSAM - Georgia Tech Smoothing and Mapping Library + +## MATLAB wrapper + +http://borg.cc.gatech.edu/projects/gtsam + +This is the GTSAM MATLAB toolbox, a MATLAB wrapper around the GTSAM C++ library. To build it, enable GTSAM_INSTALL_MATLAB_TOOLBOX in CMake. + +The interface to the toolbox is generated automatically by the wrap +tool which directly parses C++ header files. The tool generates matlab proxy objects together with all the native functions for wrapping and unwrapping scalar and non scalar types and objects. The interface generated by the wrap tool also redirects the standard output stream (cout) to matlab's console. + +## Newer Ubuntu versions unsupported by MATLAB (later than 10.04) + +If you have a newer Ubuntu system, you must make a small modification to your MATLAB installation, due to MATLAB being distributed with an old version of the C++ standard library. Delete or rename all files starting with `libstdc++` in your MATLAB installation directory, in paths: + + /usr/local/MATLAB/[version]/sys/os/[system]/ + /usr/local/MATLAB/[version]/bin/[system]/ + + +## Adding the toolbox to your MATLAB path + +To get started, first add the `toolbox` (or `gtsam_toolbox`) folder to your MATLAB path - in the MATLAB file browser, right-click on the folder and click 'Add to path -> This folder' (**do not add the subfolders to your path**). + +## Trying out the examples + +The examples are located in the 'gtsam_examples' subfolder. You may either run them individually at the MATLAB command line, or open the GTSAM example GUI by running 'gtsamExamples'. Example: + +```matlab +>> cd /Users/yourname/toolbox % Change to wherever you installed the toolbox +>> cd gtsam_examples % Change to the examples directory +>> gtsamExamples % Run the GTSAM examples GUI +``` + +## Running the unit tests + +The GTSAM MATLAB toolbox also has a small set of unit tests located in the gtsam_tests directory. Example: + +```matlab +>> cd /Users/yourname/toolbox % Change to wherever you installed the toolbox +>> cd gtsam_tests % Change to the examples directory +>> test_gtsam % Run the unit tests +Starting: testJacobianFactor +Starting: testKalmanFilter +Starting: testLocalizationExample +Starting: testOdometryExample +Starting: testPlanarSLAMExample +Starting: testPose2SLAMExample +Starting: testPose3SLAMExample +Starting: testSFMExample +Starting: testStereoVOExample +Starting: testVisualISAMExample +Tests complete! +``` + +## Writing your own code + +Coding for the GTSAM MATLAB toolbox is straightforward and very fast once you understand a few basic concepts! Please see the manual to get started. diff --git a/matlab/README-gtsam-toolbox.txt b/matlab/README-gtsam-toolbox.txt deleted file mode 100644 index a1691be32..000000000 --- a/matlab/README-gtsam-toolbox.txt +++ /dev/null @@ -1,82 +0,0 @@ -================================================================================ -GTSAM - Georgia Tech Smoothing and Mapping Library - -MATLAB wrapper - -http://borg.cc.gatech.edu/projects/gtsam -================================================================================ - -This is the GTSAM MATLAB toolbox, a MATLAB wrapper around the GTSAM C++ -library. To build it, enable GTSAM_INSTALL_MATLAB_TOOLBOX in CMake. - -The interface to the toolbox is generated automatically by the wrap -tool which directly parses C++ header files. The tool generates matlab -proxy objects together with all the native functions for wrapping and -unwrapping scalar and non scalar types and objects. The interface -generated by the wrap tool also redirects the standard output stream -(cout) to matlab's console. - ----------------------------------------- -Note about newer Ubuntu versions unsupported by MATLAB (later than 10.04) ----------------------------------------- - -If you have a newer Ubuntu system, you must make a small modification to your -MATLAB installation, due to MATLAB being distributed with an old version of -the C++ standard library. Delete or rename all files starting with -'libstdc++' in your MATLAB installation directory, in paths: - - /usr/local/MATLAB/[version]/sys/os/[system]/ - /usr/local/MATLAB/[version]/bin/[system]/ - - ----------------------------------------- -Adding the toolbox to your MATLAB path ----------------------------------------- - -To get started, first add the 'toolbox' folder to your MATLAB path - in the -MATLAB file browser, right-click on the folder and click 'Add to path -> This -folder' (do not add the subfolders to your path). - - ----------------------------------------- -Trying out the examples ----------------------------------------- - -The examples are located in the 'gtsam_examples' subfolder. You may either -run them individually at the MATLAB command line, or open the GTSAM example -GUI by running 'gtsamExamples'. Example: - ->> cd /Users/yourname/toolbox % Change to wherever you installed the toolbox ->> cd gtsam_examples % Change to the examples directory ->> gtsamExamples % Run the GTSAM examples GUI - - ----------------------------------------- -Running the unit tests ----------------------------------------- - -The GTSAM MATLAB toolbox also has a small set of unit tests located in the -gtsam_tests directory. Example: - ->> cd /Users/yourname/toolbox % Change to wherever you installed the toolbox ->> cd gtsam_tests % Change to the examples directory ->> test_gtsam % Run the unit tests -Starting: testJacobianFactor -Starting: testKalmanFilter -Starting: testLocalizationExample -Starting: testOdometryExample -Starting: testPlanarSLAMExample -Starting: testPose2SLAMExample -Starting: testPose3SLAMExample -Starting: testSFMExample -Starting: testStereoVOExample -Starting: testVisualISAMExample -Tests complete! - - ----------------------------------------- -Writing your own code ----------------------------------------- - -Coding for the GTSAM MATLAB toolbox is straightforward and very fast once you -understand a few basic concepts! Please see the manual to get started. From 366bf54f45dc10b2e9bc287b71f23b2b8aa459b5 Mon Sep 17 00:00:00 2001 From: Varun Agrawal Date: Wed, 20 Mar 2019 15:35:49 -0400 Subject: [PATCH 2/4] added instructions for performing linker setup to find libgtsam.so correctly --- matlab/README-gtsam-toolbox.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/matlab/README-gtsam-toolbox.md b/matlab/README-gtsam-toolbox.md index f23cf1da1..7e16782d4 100644 --- a/matlab/README-gtsam-toolbox.md +++ b/matlab/README-gtsam-toolbox.md @@ -21,6 +21,38 @@ If you have a newer Ubuntu system, you must make a small modification to your MA To get started, first add the `toolbox` (or `gtsam_toolbox`) folder to your MATLAB path - in the MATLAB file browser, right-click on the folder and click 'Add to path -> This folder' (**do not add the subfolders to your path**). +## Final setup on Linux + +MATLAB needs to know where the GTSAM shared object file (`libgtsam.so.4`) is so that it can link to it correctly. + +### System-wide + +If you installed GTSAM system-wide (e.g. with `sudo make install`), then simply run `sudo ldconfig`. + +### Custom Install + +If you have a custom install location, denoted by ``, you need to update your `LD_LIBRARY_PATH` environment variable. + +```sh +export LD_LIBRARY_PATH=/gtsam:$LD_LIBRARY_PATH +``` + +### Linker issues + +If you compile the Matlab toolbox and everything compiles smoothly, but when you run any Matlab script, you get following error messages in Matlab +``` +Invalid MEX-file '/usr/local/gtsam_toolbox/gtsam_wrapper.mexa64': +Missing symbol 'mexAtExit' required by '/usr/local/gtsam_toolbox/gtsam_wrapper.mexa64' +Missing symbol 'mexCallMATLABWithObject' required by '/usr/local/gtsam_toolbox/gtsam_wrapper.mexa64' +... +``` +run following shell line +```sh +export LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libstdc++.so.6:/usr/lib/x86_64-linux-gnu/libprotobuf.so.9 +``` +before you run Matlab, or write this line in your `$HOME/.bashrc` so you don't have to type everytime before start Matlab. This mainly happens if you have GCC >= 5 and newer version Matlab like R2017a. + + ## Trying out the examples The examples are located in the 'gtsam_examples' subfolder. You may either run them individually at the MATLAB command line, or open the GTSAM example GUI by running 'gtsamExamples'. Example: From 927e8a6c2796017d24fec62002c7a4905fe3850b Mon Sep 17 00:00:00 2001 From: Varun Agrawal Date: Wed, 20 Mar 2019 17:38:58 -0400 Subject: [PATCH 3/4] removed instruction to add LD_PRELOAD to .bashrc --- matlab/README-gtsam-toolbox.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/matlab/README-gtsam-toolbox.md b/matlab/README-gtsam-toolbox.md index 7e16782d4..e232c78c5 100644 --- a/matlab/README-gtsam-toolbox.md +++ b/matlab/README-gtsam-toolbox.md @@ -39,7 +39,7 @@ export LD_LIBRARY_PATH=/gtsam:$LD_LIBRARY_PATH ### Linker issues -If you compile the Matlab toolbox and everything compiles smoothly, but when you run any Matlab script, you get following error messages in Matlab +If you compile the MATLAB toolbox and everything compiles smoothly, but when you run any MATLAB script, you get following error messages in MATLAB ``` Invalid MEX-file '/usr/local/gtsam_toolbox/gtsam_wrapper.mexa64': Missing symbol 'mexAtExit' required by '/usr/local/gtsam_toolbox/gtsam_wrapper.mexa64' @@ -50,7 +50,9 @@ run following shell line ```sh export LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libstdc++.so.6:/usr/lib/x86_64-linux-gnu/libprotobuf.so.9 ``` -before you run Matlab, or write this line in your `$HOME/.bashrc` so you don't have to type everytime before start Matlab. This mainly happens if you have GCC >= 5 and newer version Matlab like R2017a. +before you run MATLAB. + +This mainly happens if you have GCC >= 5 and newer version MATLAB like R2017a. ## Trying out the examples From 53e74a8070dc4aa42460302e9100d1fb0f20cde1 Mon Sep 17 00:00:00 2001 From: Varun Agrawal Date: Sun, 24 Mar 2019 22:18:42 -0400 Subject: [PATCH 4/4] further updated MATLAB instructions to remove inconsistencies and oddities --- matlab/README-gtsam-toolbox.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/matlab/README-gtsam-toolbox.md b/matlab/README-gtsam-toolbox.md index e232c78c5..66a02e969 100644 --- a/matlab/README-gtsam-toolbox.md +++ b/matlab/README-gtsam-toolbox.md @@ -4,14 +4,14 @@ http://borg.cc.gatech.edu/projects/gtsam -This is the GTSAM MATLAB toolbox, a MATLAB wrapper around the GTSAM C++ library. To build it, enable GTSAM_INSTALL_MATLAB_TOOLBOX in CMake. +This is the GTSAM MATLAB toolbox, a MATLAB wrapper around the GTSAM C++ library. To build it, enable `GTSAM_INSTALL_MATLAB_TOOLBOX=ON` in CMake. The interface to the toolbox is generated automatically by the wrap tool which directly parses C++ header files. The tool generates matlab proxy objects together with all the native functions for wrapping and unwrapping scalar and non scalar types and objects. The interface generated by the wrap tool also redirects the standard output stream (cout) to matlab's console. -## Newer Ubuntu versions unsupported by MATLAB (later than 10.04) +## Ubuntu -If you have a newer Ubuntu system, you must make a small modification to your MATLAB installation, due to MATLAB being distributed with an old version of the C++ standard library. Delete or rename all files starting with `libstdc++` in your MATLAB installation directory, in paths: +If you have a newer Ubuntu system (later than 10.04), you must make a small modification to your MATLAB installation, due to MATLAB being distributed with an old version of the C++ standard library. Delete or rename all files starting with `libstdc++` in your MATLAB installation directory, in paths: /usr/local/MATLAB/[version]/sys/os/[system]/ /usr/local/MATLAB/[version]/bin/[system]/ @@ -48,9 +48,9 @@ Missing symbol 'mexCallMATLABWithObject' required by '/usr/local/gtsam_toolbox/g ``` run following shell line ```sh -export LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libstdc++.so.6:/usr/lib/x86_64-linux-gnu/libprotobuf.so.9 +export LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libstdc++.so.6 ``` -before you run MATLAB. +before you run MATLAB from the same shell. This mainly happens if you have GCC >= 5 and newer version MATLAB like R2017a.